From 18deeb7a35f8612b37b0819800ee1de8cfaba515 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Torbj=C3=B6rn=20Klatt?= Date: Thu, 2 Apr 2015 19:54:35 +0200 Subject: [PATCH 01/12] docu: adding docu modules - Controllers - Internals - Utilities - Examples --- include/pfasst.hpp | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/include/pfasst.hpp b/include/pfasst.hpp index ca094875..5781afc7 100644 --- a/include/pfasst.hpp +++ b/include/pfasst.hpp @@ -23,4 +23,21 @@ namespace pfasst } } // ::pfasst + +/** + * @defgroup Controllers + * Controllers represent the main entry point of PFASST++ as they ensemble the central algorithmic + * logic of PFASST and related algorithms. + * + * @defgroup Internals + * Entities listed in this module are ment to be for internal use only and should not be used + * outside of PFASST++ itself. + * + * @defgroup Utilities + * General utility functions not directly related to PFASST++ but also handy in user code. + * + * @defgroup Examples + * A few different examples demonstrating the use and functionality of PFASST++. + */ + #endif From 3891c1620af829cf2d3114bee08af6e4a02bcedc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Torbj=C3=B6rn=20Klatt?= Date: Thu, 2 Apr 2015 19:53:46 +0200 Subject: [PATCH 02/12] docu: improve utilities and general stuff --- include/pfasst/config.hpp | 150 ++++++++++++++++++++++++++- include/pfasst/globals.hpp | 34 +++--- include/pfasst/interfaces.hpp | 182 ++++++++++++++++++++++++++------- include/pfasst/logging.hpp | 157 +++++++++++++++++++++------- src/pfasst/config_impl.hpp | 47 +++------ src/pfasst/interfaces_impl.hpp | 41 ++++++-- 6 files changed, 474 insertions(+), 137 deletions(-) diff --git a/include/pfasst/config.hpp b/include/pfasst/config.hpp index 2d2a4779..9bfbbd5a 100644 --- a/include/pfasst/config.hpp +++ b/include/pfasst/config.hpp @@ -1,3 +1,7 @@ +/** + * @file pfasst/config.hpp + * @since v0.3.0 + */ #ifndef _PFASST__CONFIG_HPP_ #define _PFASST__CONFIG_HPP_ @@ -13,15 +17,25 @@ namespace po = boost::program_options; namespace pfasst { + /** + * @since v0.3.0 + */ namespace config { /** + * runtime config options provider. + * + * This singleton provides easy access to command line parameters at runtime. + * * @note This uses the Singleton Pattern, and hence pfasst::options::get_instance() is * thread-safe with C++11. + * @since v0.3.0 + * @ingroup Internals */ class options { public: + /// line width of help and usage information static const size_t LINE_WIDTH = 100; private: @@ -31,34 +45,140 @@ namespace pfasst vector unrecognized_args; bool initialized = false; + //! @{ options(); options(const options&) = delete; void operator=(const options&) = delete; + //! @} public: + //! @{ + /** + * accessor to the singleton instance. + * + * @returns singleton config::options instance + */ static options& get_instance(); po::variables_map& get_variables_map(); po::options_description& get_all_options(); vector& get_unrecognized_args(); + //! @} + + //! @{ + /** + * adds a new boolean flag. + * + * @param[in] group string identifying the parameter group + * @param[in] option Name of the command line parameter. + * It is possible to specify a long and optional short option name by comma-separation. + * Short option names are identified by being only a single character. + * They are automatically parsed as '`-[SHORT]`' by `boost::program_options` in contrast + * to '`--[LONG]`'. + * @param[in] help help text to be displayed in the help and usage information + */ static void add_option(const string& group, const string& option, const string& help); + /** + * adds a new parameter with an expected value of type @p T. + * + * @tparam T type of the specified parameter + * @param[in] group string identifying the parameter group + * @param[in] option Name of the command line parameter. + * It is possible to specify a long and optional short option name by comma-separation. + * Short option names are identified by being only a single character. + * They are automatically parsed as '`-[SHORT]`' by `boost::program_options` in contrast + * to '`--[LONG]`'. + * @param[in] help help text to be displayed in the help and usage information + * + * @overload + */ template static void add_option(const string& group, const string& option, const string& help); + //! @} + /** + * initialize program options. + * + * This initializes `boost::program_options` with all previously added options and groups. + */ void init(); }; + /** + * get value of specific type @p T + * + * @tparam T type of the retreived value + * @param[in] name Name of the (long) option as defined with @p option in options::add_option() + * @returns Value of type @p T of desired option. + * @throws boost::bad_any_cast if option is not given. + * + * @see + * [boost::any::bad_any_cast] + * (http://www.boost.org/doc/libs/1_57_0/doc/html/boost/bad_any_cast.html) + */ template - static T get_value(const string& name, const T& default_val); + inline T get_value(const string& name) + { + return options::get_instance().get_variables_map()[name].as(); + } + /** + * get value of specific type @p T with default value. + * + * @tparam T type of the retreived value + * + * @overload + */ template - static T get_value(const string& name); + inline T get_value(const string& name, const T& default_val) + { + return options::get_instance().get_variables_map().count(name) + ? options::get_instance().get_variables_map()[name].as() : default_val; + } /** - * @returns empty string if params are set and `if_no_params` is `true` + * compile basic help and usage information. + * + * Depending on @p if_no_params and presence of given command line parameters the help and + * usage information is compiled. + * In case @p if_no_params is `true` and there are no parameters given on the command line or + * @p if_no_params is `false` no matter whether parameters are given, the help message is + * generated. + * + * @param[in] if_no_params flag governing compilation of help and usage information + * @returns string containing basic help and usage information; string may be empty */ - static string print_help(bool if_no_params = false); + static string print_help(bool if_no_params = false) + { + bool no_params_given = options::get_instance().get_variables_map().empty(); + + if (!if_no_params || (if_no_params && no_params_given)) { + stringstream s; + s << options::get_instance().get_all_options() << endl; + s << "Logging options:" << endl + << " -v [ --verbose ] activates maximum verbosity" << endl + << " --v=arg activates verbosity upto verbose level `arg`" << endl + << " (valid range: 0-9)" << endl + << " -vmodule=arg actives verbose logging for specific module" << endl + << " (see [1] for details)" << endl << endl + << "[1]: https://github.com/easylogging/easyloggingpp#vmodule" << endl; + return s.str(); + } else { + return string(); + } + } + /** + * read and parse command line parameters. + * + * @param[in] argc Number of command line arguments as provided by `%main(int, char**)`. + * @param[in] argv List of command line arguments as provided by `%main(int, char**)`. + * @param[in] exit_on_help Whether to exit the program after displaying help and usage + * information. + * + * @note Will call `std::exit` in case the `help` parameter has been provided and + * @p exit_on_help is `true`. + */ static inline void read_commandline(int argc, char* argv[], bool exit_on_help = true) { po::parsed_options parsed = po::command_line_parser(argc, argv) @@ -76,7 +196,15 @@ namespace pfasst } /** + * read config parameters from file. + * + * @param[in] file_name name of the INI-like file containing config parameters; + * path/name may be relative * @throws invalid_argument if the given file could not be opened + * + * @see + * [Boost Program Options Documentation on supported INI-like file format] + * (http://www.boost.org/doc/libs/1_57_0/doc/html/program_options/overview.html#idp343292240) */ static inline void read_config_file(const string& file_name) { @@ -90,6 +218,20 @@ namespace pfasst } } + /** + * initialize options detection and parsing. + * + * Prepopulates following groups and parameters: + * + * Group | Parameter | Type + * -----------|---------------|--------- + * Global | `h`, `help` | `bool` + * Duration | `dt` | `double` + * Duration | `tend` | `double` + * Duration | `num_iters` | `size_t` + * Tolerances | `abs_res_tol` | `double` + * Tolerances | `rel_res_tol` | `double` + */ static inline void init() { options::add_option("Global", "help,h", "display this help message"); diff --git a/include/pfasst/globals.hpp b/include/pfasst/globals.hpp index 80d2d3f0..5227e820 100644 --- a/include/pfasst/globals.hpp +++ b/include/pfasst/globals.hpp @@ -1,30 +1,36 @@ +/** + * @file pfasst/globals.hpp + * @since v0.2.0 + */ #ifndef _GLOBALS__HPP_ #define _GLOBALS__HPP_ /** - * denoting unused function parameters for omitting compiler warnings + * denoting unused function parameters for omitting compiler warnings. * * To denote an unused function parameter just use this makro on it in the function body: - * - * ~~~{.cpp} - * void func(auto p) { - * UNUSED(p); + * @code{.cpp} + * void foo(T bar) { + * UNUSED(bar); + * // some logic not using parameter `bar` * } - * ~~~ - * + * @endcode * which renders to - * - * ~~~{.cpp} - * void func(auto p) { - * (void)(p); + * @code{.cpp} + * void foo(T bar) { + * (void)(bar); + * // some logic not using parameter `bar` * } - * ~~~ - * + * @endcode * which is the standard and compiler independet way of omitting warnings on unused parameters while * still being able to fully document the parameter with Doxygen. * * @param[in] expr parameter to be denoted as unused + * @since v0.2.0 + * @ingroup Utilities */ -#define UNUSED(expr) (void)(expr) +#define UNUSED(expr) \ + (void)(expr) + #endif // _GLOBALS__HPP_ diff --git a/include/pfasst/interfaces.hpp b/include/pfasst/interfaces.hpp index f6f195ea..4be424ea 100644 --- a/include/pfasst/interfaces.hpp +++ b/include/pfasst/interfaces.hpp @@ -1,7 +1,9 @@ -/* - * Interfaces for SDC/MLSDC/PFASST algorithms. +/** + * interfaces for SDC/MLSDC/PFASST algorithms. + * + * @file pfasst/interfaces.hpp + * @since v0.1.0 */ - #ifndef _PFASST_INTERFACES_HPP_ #define _PFASST_INTERFACES_HPP_ @@ -21,6 +23,8 @@ namespace pfasst * * Used by PFASST to mark methods that are required for a particular algorithm (SDC/MLSDC/PFASST) * that may not be necessary for all others. + * + * @since v0.1.0 */ class NotImplementedYet : public runtime_error @@ -41,6 +45,10 @@ namespace pfasst * value exception. * * Thrown when a PFASST routine is passed an invalid value. + * + * @since v0.1.0 + * + * @todo Consider deprecating this in favour of std::invalid_argument. */ class ValueError : public invalid_argument @@ -57,6 +65,14 @@ namespace pfasst // forward declare for IStatus class IStatus; + + /** + * abstract interface for communicators. + * + * The interface ensures a communicator provides the notion of the total number of processors + * (i.e. `size()`) and and the ID of the _current_ processor (i.e. `rank()`) as well as the + * current @ref ICommunicator::status "status" of the algorithm. + */ class ICommunicator { public: @@ -68,6 +84,12 @@ namespace pfasst }; + /** + * abstract interface for the current status of the algorithm. + * + * The status requires a @ref ICommunicator "communicator" to enable sending and receiving stati + * of other processors. + */ class IStatus { protected: @@ -75,16 +97,58 @@ namespace pfasst public: virtual ~IStatus(); + + //! @{ + /** + * resetting status. + * + * @note Logic is implementation defined. + */ virtual void clear() = 0; + + /** + * sets a new converged state. + */ virtual void set_converged(bool converged) = 0; + + /** + * retreive converged state for specific processor. + * + * @param[in] rank ID of processor to check converged state for + * @returns `true` if processor with ID @p rank has converged; `false` otherwise + * + * @note Inspection logic is implementation defined. + */ virtual bool get_converged(int rank) = 0; - virtual void post() = 0; - virtual void send() = 0; - virtual void recv() = 0; + //! @} + //! @{ + /** + * set new communicator to use. + */ virtual void set_comm(ICommunicator* comm); + + /** + * check whether previous processor is still iterating. + * + * @returns `true` if previous processor has converged; `false` if it is still iterating + */ virtual bool previous_is_iterating(); + + /** + * check whether this processor should keep iterating. + * + * @returns `true` if this processor should keep iterating; `false` if it should switch to + * `converged` state + */ virtual bool keep_iterating(); + //! @} + + //! @{ + virtual void post() = 0; + virtual void send() = 0; + virtual void recv() = 0; + //! @} }; @@ -92,15 +156,19 @@ namespace pfasst template class Controller; + /** * abstract SDC sweeper. - * @tparam time time precision; - * defaults to pfasst::time_precision + * + * @tparam time time precision; defaults to pfasst::time_precision */ template class ISweeper { protected: + /** + * backreference to the controller managing the sweeper instance. + */ Controller