This tutorial gives some simple examples of how to write an mlpack binding that can be compiled for multiple languages. These bindings make up the core of how most users will interact with mlpack.
mlpack provides the following:
- mlpack::Log, for debugging / informational / warning / fatal output
- mlpack::CLI, for parsing command line options or other option
Each of those classes are well-documented, and that documentation should be consulted for further reference.
First, we'll discuss the logging infrastructure, which is useful for giving output that users can see.
mlpack has four logging levels:
Output to Log::Debug does not show (and has no performance penalty) when mlpack is compiled without debugging symbols. Output to Log::Info is only shown when the program is run with the
-v) flag. Log::Warn is always shown, and Log::Fatal will throw a std::runtime_error exception, after a newline is sent to it. If mlpack was compiled with debugging symbols, Log::Fatal will also print a backtrace, if the necessary libraries are available.
Here is a simple example binding, and its output. Note that instead of
main(), we use
mlpackMain(). This is because the automatic binding generator (see mlpack automatic bindings to other languages) will set up the environment and once that is done, it will call
Assuming mlpack is installed on the system and the code above is saved in
test.cpp, this program can be compiled with the following command:
Since we compiled with
-DDEBUG, if we run the program as below, the following output is shown:
-rdynamic are only necessary for providing a backtrace. If those flags are not given during compilation, the following output would be shown:
The last warning is not reached, because Log::Fatal terminates the program.
Without debugging symbols (i.e. without
-DDEBUG) and without –verbose, the following is shown:
These four outputs can be very useful for both providing informational output and debugging output for your mlpack program.
Through the mlpack::CLI object, command-line parameters can be easily added with the PROGRAM_INFO, PARAM_INT, PARAM_DOUBLE, PARAM_STRING, and PARAM_FLAG macros.
Here is a sample use of those macros, extracted from methods/pca/pca_main.cpp. (Some details have been omitted from the snippet below.)
Documentation is automatically generated using those macros, and when the program is run with –help the following is displayed:
The mlpack::CLI documentation can be consulted for further and complete documentation. Also useful is to look at other example bindings, found in
Generated by 1.8.13