tk namespace

enum tk::ErrCode

Error codes for the OS (or whatever calls us)

template<class li, class lo>

using tk::cartesian_product = brigand::reverse_fold<brigand::list<li, lo>, brigand::list<brigand::list<>>, brigand::bind<brigand::join, brigand::bind<brigand::transform, brigand::_2, brigand::defer<brigand::bind<brigand::join, brigand::bind<brigand::transform, brigand::parent<brigand::_1>, brigand::defer<brigand::bind<brigand::list, brigand::bind<brigand::push_front, brigand::_1, brigand::parent<brigand::_1>>>>>>>>>>

Cartesian product of two brigand lists

template<std::size_t N>

using tk::Table = std::vector<std::array<real, N+1>>

Type alias for storing a discrete (y1,y2,...,yN) = f(x) function

template<class Container>

void tk::unique(Container& c)

Make elements of container unique (in-place, overwriting source container)

template<class Container>

Container tk::uniquecopy(const Container& src)

Make elements of container unique (on a copy, leaving the source as is)

template<typename Container>

auto tk::cref_find(const Container& map, const typename Container::key_type& key) -> const typename Container::mapped_type &

Find and return a constant reference to value for key in container that provides a find() member function with error handling.

template<typename Container>

auto tk::ref_find(const Container& map, const typename Container::key_type& key) -> typename Container::mapped_type &

Find and return a reference to value for key in a container that provides a find() member function with error handling.

template<typename T>

std::array<T, 2> tk::extents(const std::vector<T>& vec)

Return minimum and maximum values of a vector.

template<typename Container>

auto tk::extents(const Container& map) -> std::array< typename Container::mapped_type, 2 >

Find and return minimum and maximum values in associative container.

template<class T, std::size_t N>

std::array<T, N>& tk::operator+=(std::array<T, N>& dst, const std::array<T, N>& src)

Add all elements of an array to those of another one

template<class T, class Allocator>

std::vector<T, Allocator>& tk::operator+=(std::vector<T, Allocator>& dst, const std::vector<T, Allocator>& src)

Add all elements of a vector to those of another one If src.size() > dst.size() will grow dst to that of src.size() padding with zeros.

template<class T, class Allocator>

std::vector<T, Allocator>& tk::operator/=(std::vector<T, Allocator>& dst, const std::vector<T, Allocator>& src)

Divide all elements of a vector with those of another one If src.size() > dst.size() will grow dst to that of src.size() padding with zeros.

template<class C1, class C2>

bool tk::keyEqual(const C1& a, const C2& b)

Test if all keys of two associative containers are equal

template<class Container>

std::size_t tk::sumsize(const Container& c)

Compute the sum of the sizes of a container of containers

template<class Container>

std::size_t tk::numunique(const Container& c)

Compute the number of unique values in a container of containers

template<class Map>

std::size_t tk::sumvalsize(const Map& c)

Compute the sum of the sizes of the values of an associative container

template<class Container>

void tk::destroy(Container& c)

Free memory of a container See http://stackoverflow.com/a/10465032 as to why this is done with the swap() member function of the container.

template<typename Container, typename Predicate>

void tk::erase_if(Container& items, const Predicate& predicate)

Remove items from container based on predicate

template<class T>

void tk::concat(std::vector<T>&& src, std::vector<T>& dst)

Concatenate vectors of T

template<class T>

void tk::concat(std::vector<std::pair<bool, T>>&& src, std::vector<std::pair<bool, T>>& dst)

Overwrite vectors of pair< bool, tk::real >

template<class Key, class Hash = std::hash<Key>, class Eq = std::equal_to<Key>>

void tk::concat(std::unordered_set<Key, Hash, Eq>&& src, std::unordered_set<Key, Hash, Eq>& dst)

Concatenate unordered sets

template<class Key, class Value>

std::ostream& tk::operator<<(std::ostream& os, const std::pair<const Key, Value>& v)

Operator << for writing value_type of a standard map to output streams

template<typename T>

std::string tk::parameter(const T& v)

Convert and return value as string.

template<typename V>

std::string tk::parameters(const V& v)

Convert and return values from container as string.

template<uint8_t Layout>

Data<Layout> tk::operator*(tk::real lhs, const Data<Layout>& rhs)

Operator * multiplying all items by a scalar from the left

template<uint8_t Layout>

Data<Layout> tk::min(const Data<Layout>& a, const Data<Layout>& b)

Operator min between two Data objects

template<uint8_t Layout>

Data<Layout> tk::max(const Data<Layout>& a, const Data<Layout>& b)

Operator max between two Data objects

template<uint8_t Layout>

bool tk::operator==(const Data<Layout>& lhs, const Data<Layout>& rhs)

Operator == between two Data objects

template<uint8_t Layout>

bool tk::operator!=(const Data<Layout>& lhs, const Data<Layout>& rhs)

Operator != between two Data objects

template<uint8_t Layout>

std::pair<std::size_t, tk::real> tk::maxdiff(const Data<Layout>& lhs, const Data<Layout>& rhs)

Compute the maximum difference between the elements of two Data objects The position returned is the position in the underlying raw data structure, independent of components, offsets, etc. If lhs == rhs with precision std::numeric_limits< tk::real >::epsilon(), a pair of (0,0.0) is returned.

template<class C, class Key, class Factory, typename... ConstructorArgs>

void tk::record(Factory& f, const Key& key, ConstructorArgs&&... args)

Register class into factory with given key. This is used to register a derived-class object's constructor (deriving from some base class) to a factory. The factory itself is a std::map< key, std::function< Child*() > >, i.e., an associative container, associating some key to a std::function object holding a pointer of Child's base class constructor. The constructor and its bound arguments are stored via boost::factory, which, in this use-case, yields the correct function object of type Base constructor pointer and thus facilitates runtime polymorphism. This function works in conjunction with boost::factory, i.e., uses reference semantics (works with storing pointers of objects). For a simple example on how to use this function, see tests/unit/Base/Factory.h.

template<class Factory, class Key, class Obj = typename std::remove_pointer< typename Factory::mapped_type::result_type>::type>

std::unique_ptr<Obj> tk::instantiate(const Factory& f, const Key& key)

Instantiate object from factory. Factory must have a mapped_value which must have a result_type ptr, e.g., std::map< Key, std::function< Obj*() > >. This wrapper function can be used to instantiate an derived-class object from a factory, repeatedly filled with wrapper function 'record' above. The factory, as described in the documentation of 'record', stores base class pointers in an associative container, thereby facilitating runtime polymorphism and a simple lookup-and-instantiate-style object creation. The object instantiated is of type Child class. This function works in conjunction with boost::factory, i.e., uses reference semantics (works with storing pointers of objects). For a simple example on how to use this function, see tests/unit//Base/Factory.h.

template<class Host, class ModelConstructor, class Factory, class Key, typename... ModelConstrArgs>

void tk::recordModel(Factory& f, const Key& key, ModelConstrArgs&&... args)

Register "model" class of "host" into factory with given key. This wrapper can be used to in a similar manner to 'record', but uses boost::value_factory to bind the model object constructor to its arguments and place it in the associative container storing host class objects. The container is thus of type std::map< key, std::function< T() > >, i.e., associating a key to a function holding a constructor (and not its pointer). Runtime polymorphism here is realized entirely within the "base" class. See walker::DiffEq in DiffEq/DiffEq.h for an example and more information on runtime polymorphism without client-side inheritance. As a result, this wrapper works with factories that use value semantics, as opposed to 'record' and instantiate which work with reference semantics factories. In order to differentiate between runtime polymorphic classes using reference semantics, consistent with classes realizing runtime polymorphism without client-side inheritance, we call Host as the "Base" class and Model as the "derived" (or child) class. This wrapper function works in conjunction with boost::value_factory, i.e., uses value semantics (works with storing objects instead of object pointers). For a simple example on how to use this function, see tests/unit//Base/Factory.h.

template<class Host, class ModelConstructor, class Factory, class Key, typename ModelConstrArg>

void tk::recordModelLate(Factory& f, const Key& key, ModelConstrArg)

Register model class of host into factory with given key using late binding. This variant of 'record' is very similar to 'recordModel', but registers a model class constructor to a factory with late binding of the constructor argument. Late binding allows specifying the constructor argument at the time when the object is instantiated instead of at the time when it is registered. This has all the benefits of using a factory and allows passing information into the model object only when it is available. The late bind is facilitated via std::bind instead of std::bind using a placeholder, _1, which stands for the first argument (bound later, i.e., not here). The value of the model constructor argument is then not used here, only its type, used to perform the late binding. The binding happens to both the model constructor via std::function (passed to the host constructor) as well as explicitly to the host constructor. Prescribing late binding to the model constructor ensures that the compiler requires the argument to the model constructor, i.e., ensures that the host constructor is required to pass the argument to the model constructor. Prescribing late binding to the host constructor puts in the actual request that an argument (with the correct type) must be passed to the host constructor at instantiate time, which then will forward it to the model constructor. See also, for example, walker::DiffEq's corresponding constructor. An example of client-side code is in walker::DiffEqStack::registerDiffEq for registration into factory, and DiffEqStack::createDiffEq for instantiation late-passing the argument.

template<class Host, class ModelConstructor, class Factory, class Key, typename... ModelConstrArgs>

void tk::recordCharmModel(Factory& f, const Key& key, ModelConstrArgs&&... args)

Register Charm++ model class of host into factory with given key. We bind a host constructor to its arguments of which the first one is a std::function holding a model constructor type (modeling, i.e., used polymorhically with host), followed by an optional number of others (possibly zero) with arbitrary types. Note that the model constructor is a nullptr (default- constructed) and only used to forward its type to the call site inside std::function. The host constructor function is then placed into the factory. This is because Charm++ chares do not explicitly invoke constructors, only call ckNew() on their proxy, which requires all constructor arguments to be present and forwarded to the actual constructor that is only called at a later point in time. This can then be used by those constructors of hosts that invoke the model constructors' proxies' ckNew() and ignore the std::function. See, e.g., rngtest::Battery() and the associated unit tests in tests/unit//Base/Factory.h.

template<typename A, typename B>

std::pair<B, A> tk::flip_pair(const std::pair<A, B>& p)

Flip a std::pair of arbitrary types

template<typename A, typename B>

std::multimap<B, A> tk::flip_map(const std::map<A, B>& src)

Flip a std::map of arbitrary types, yielding a std::multimap sorted by std::map::value_type.

template<class Key, class T, class Hash = std::hash<Key>, class Eq = std::equal_to<Key>>

std::pair<int, std::unique_ptr<char[]>> tk::serialize(const std::unordered_map<Key, T, Hash, Eq>& m)

Serialize std::unordered_map to raw memory stream

template<class Key, class T, class Hash = std::hash<Key>, class Eq = std::equal_to<Key>>

CkReductionMsg* tk::mergeHashMap(int nmsg, CkReductionMsg** msgs)

Charm++ custom reducer for merging std::unordered_maps during reduction across PEs.

During aggregation the map keys are inserted, i.e., the keys remain unique and the mapped values, assuming containers defining begin() and end() iterators() are concatenated.

uint64_t tk::linearLoadDistributor(real virtualization, uint64_t load, int npe, uint64_t& chunksize, uint64_t& remainder)

Compute linear load distribution for given total work and virtualization.

Compute load distibution (number of chares and chunksize) based on total work (e.g., total number of particles) and virtualization

The virtualization parameter, specified by the user, is a real number between 0.0 and 1.0, inclusive, which controls the degree of virtualization or over-decomposition. Independent of the value of virtualization the work is approximately evenly distributed among the available processing elements, given by npe. For zero virtualization (no over-decomposition), the work is simply decomposed into total_work/numPEs, which yields the smallest number of Charm++ chares and the largest chunks of work units. The other extreme is unity virtualization, which decomposes the total work into the smallest size work units possible, yielding the largest number of Charm++ chares. Obviously, the optimum will be between 0.0 and 1.0, depending on the problem.

The formula implemented uses a linear relationship between the virtualization parameter and the number of work units with the extremes described above. The formula is given by

chunksize = (1 - n) * v + n;

where

• v = degree of virtualization
• n = load/npes
• load = total work, e.g., number of particles, number of mesh cells
• npes = number of hardware processing elements

template<typename Enum, typename Ch, typename Tr, typename std::enable_if_t<std::is_enum_v<Enum>, int> = 0>

std::basic_ostream<Ch, Tr>& tk::operator<<(std::basic_ostream<Ch, Tr>& os, const Enum& e)

Operator << for writing an enum class to an output stream

template<class T, typename Ch, typename Tr>

std::basic_ostream<Ch, Tr>& tk::operator<<(std::basic_ostream<Ch, Tr>& os, const std::vector<T>& v)

Operator << for writing a std::vector to an output stream

template<typename Ch, typename Tr, class Key, class Value, class Compare = std::less<Key>>

std::basic_ostream<Ch, Tr>& tk::operator<<(std::basic_ostream<Ch, Tr>& os, const std::map<Key, Value, Compare>& m)

Operator << for writing an std::map to an output stream

template<typename T, typename Ch, typename Tr>

std::basic_string<Ch, Tr> tk::operator<<(std::basic_string<Ch, Tr>& lhs, const T& e)

Operator << for adding (concatenating) T to a std::basic_string for lvalues.

template<typename T, typename Ch, typename Tr>

std::basic_string<Ch, Tr> tk::operator<<(std::basic_string<Ch, Tr>&& lhs, const T& e)

Operator << for adding (concatenating) T to a std::basic_string for rvalues.

std::string tk::splitLines(std::string str, std::string indent, const std::string& name = "", std::size_t width = 80)

Clean up whitespaces and format a long string into multiple lines.

std::string tk::baselogname(const std::string& executable)

std::string tk::logname(const std::string& executable, int numrestart = 0)

Construct log file name.

void tk::rm(const std::string& file)

Remove file from file system.

Since we use pstream's basic_ipstream constructor with signature ( const std::string & file, const argv_type & argv, pmode mode = pstdout ) and the file argument doesn't contain a slash, the actions of the shell are duplicated in searching for an executable in PATH. The shell will not interpret the other arguments, so wildcard expansion will not take place.

void tk::signalHandler(int signum)

Signal handler for multiple signals, SIGABRT, SIGSEGV, etc.

Signals caught: SIGABRT is generated when the program calls the abort() function, such as when an assert() triggers SIGSEGV is generated when the program makes an illegal memory access, such as reading unaligned memory, dereferencing a null pointer, reading memory out of bounds etc. SIGILL is generated when the program tries to execute a malformed instruction. This happens when the execution pointer starts reading non-program data, or when a pointer to a function is corrupted. SIGFPE is generated when executing an illegal floating point instruction, most commonly division by zero or floating point overflow.

int tk::setSignalHandlers()

Set signal handlers for multiple signals, SIGABRT, SIGSEGV, etc.

void tk::processExceptionCharm()

Process an exception from the Charm++ runtime system.

See Josuttis, The C++ Standard Library - A Tutorial and Reference, 2nd Edition, 2012.

template<typename T>

T tk::swap_endian(T u)

Swap endianness of an integral type

template<>

double tk::swap_endian(double u)

Swap endianness of a double

template<std::size_t N>

std::array<real, N> tk::sample(real x, const Table<N>& table)

Sample a discrete (y1,y2,...,yN) = f(x) function at x

template<class Tuple>

void tk::print(std::ostream& os, const std::string& name, const Tuple& c)

Output command line object (a TaggedTuple) to file

template<class List>

std::ostream& tk::operator<<(std::ostream& os, const tk::TaggedTuple<List>& t)

Simple (unformatted, one-line) output of a TaggedTuple to output stream

template<class List, class Ignore = brigand::set<>>

void tk::print(std::ostream& os, const tk::TaggedTuple<List>& t)

Simple (unformatted, one-line) output of a TaggedTuple to output stream with ignore.

Timer::Watch tk::hms(tk::real stamp)

Convert existing time stamp as a real to Watch (global scope)

Convert existing time stamp as a real to Watch (global-scope)

void tk::flip(std::array<real, 3>& v)

Flip sign of vector components

void tk::cross(real v1x, real v1y, real v1z, real v2x, real v2y, real v2z, real& rx, real& ry, real& rz)

Compute the cross-product of two vectors

std::array<real, 3> tk::cross(const std::array<real, 3>& v1, const std::array<real, 3>& v2)

Compute the cross-product of two vectors

void tk::crossdiv(real v1x, real v1y, real v1z, real v2x, real v2y, real v2z, real j, real& rx, real& ry, real& rz)

Compute the cross-product of two vectors divided by a scalar

std::array<real, 3> tk::crossdiv(const std::array<real, 3>& v1, const std::array<real, 3>& v2, real j)

Compute the cross-product of two vectors divided by a scalar

real tk::dot(const std::array<real, 3>& v1, const std::array<real, 3>& v2)

Compute the dot-product of two vectors

real tk::length(real x, real y, real z)

Compute length of a vector

real tk::length(const std::array<real, 3>& v)

Compute length of a vector

void tk::unit(std::array<real, 3>& v)

Scale vector to unit length

tk::real tk::triple(real v1x, real v1y, real v1z, real v2x, real v2y, real v2z, real v3x, real v3y, real v3z)

Compute the triple-product of three vectors

real tk::triple(const std::array<real, 3>& v1, const std::array<real, 3>& v2, const std::array<real, 3>& v3)

Compute the triple-product of three vectors

std::array<real, 3> tk::rotateX(const std::array<real, 3>& v, real angle)

Rotate vector about X axis

std::array<real, 3> tk::rotateY(const std::array<real, 3>& v, real angle)

Rotate vector about Y axis

std::array<real, 3> tk::rotateZ(const std::array<real, 3>& v, real angle)

Rotate vector about Z axis

real tk::Jacobian(const std::array<real, 3>& v1, const std::array<real, 3>& v2, const std::array<real, 3>& v3, const std::array<real, 3>& v4)

Compute the determinant of the Jacobian of a coordinate transformation over a tetrahedron.

std::array<std::array<real, 3>, 3> tk::inverseJacobian(const std::array<real, 3>& v1, const std::array<real, 3>& v2, const std::array<real, 3>& v3, const std::array<real, 3>& v4)

Compute the inverse of the Jacobian of a coordinate transformation over a tetrahedron.

tk::real tk::determinant(const std::array<std::array<tk::real, 3>, 3>& a)

Compute the determinant of 3x3 matrix

std::array<tk::real, 3> tk::cramer(const std::array<std::array<tk::real, 3>, 3>& a, const std::array<tk::real, 3>& b)

Solve a 3x3 system of equations using Cramer's rule

static std::string tk::workdir()

std::string tk::curtime()

Wrapper for the standard C library's gettimeofday() from.

void tk::echoHeader(const Print& print, HeaderType header)

Echo program header.

void tk::echoBuildEnv(const Print& print, const std::string& executable)

Echo build environment.

Echo information read from build_dir/Base/Config.h filled by CMake based on src/Main/Config.h.in.

void tk::echoRunEnv(const Print& print, int argc, char** argv, bool verbose, bool quiescence, bool charestate, bool trace, const std::string& screen_log, const std::string& input_log)

Echo runtime environment.

template<class Driver, class CmdLine>

Driver tk::Main(int argc, char* argv[], const CmdLine& cmdline, HeaderType header, const std::string& executable, const std::string& def, int nrestart)

Generic Main() used for all executables for code-reuse and a uniform output.

The template arguments configure this Main class that is practically used instead of the usual main(). This allows code-reuse and a unfirom screen-output. The template arguments are:

• Driver, specializaing the driver type to be created, see tk::Driver
• Printer, specializaing the pretty printer type to use, see tk::Print
• CmdLine, specializing the command line object storing data parsed from the command line

template<class MainProxy, class CmdLine>

void tk::MainCtor(MainProxy& mp, const MainProxy& thisProxy, std::vector<tk::Timer>& timer, const CmdLine& cmdline, const CkCallback& quiescenceTarget)

Generic Main Charm++ module constructor for all executables

template<class CmdLine>

void tk::dumpstate(const CmdLine& cmdline, const std::string& def, int nrestart, CkReductionMsg* msg)

Generic function to dump the Charm++ chare state (if collected)

template<class CmdLine>

void tk::finalize(const CmdLine& cmdline, const std::vector<tk::Timer>& timer, tk::CProxy_ChareStateCollector& state, std::vector<std::pair<std::string, tk::Timer::Watch>>& timestamp, const std::string& def, int nrestart, const CkCallback& dumpstateTarget, bool clean = true)

Generic finalize function for different executables

std::pair<int, std::unique_ptr<char[]>> tk::serialize(std::size_t meshid, const std::vector<tk::UniPDF>& u)

Serialize univariate PDF to raw memory stream.

CkReductionMsg* tk::mergeUniPDFs(int nmsg, CkReductionMsg** msgs)

Charm++ custom reducer for merging a univariate PDF during reduction across PEs.

std::pair<int, std::unique_ptr<char[]>> tk::serialize(const std::vector<tk::UniPDF>& u, const std::vector<tk::BiPDF>& b, const std::vector<tk::TriPDF>& t)

Serialize vectors of PDFs to raw memory stream.

CkReductionMsg* tk::mergePDF(int nmsg, CkReductionMsg** msgs)

Charm++ custom reducer for merging PDFs during reduction across PEs.

static std::ostream& tk::operator<<(std::ostream& os, const tk::UniPDF& p)

Output univariate PDF to output stream