\section{Introduction}\label{iodoc_iointro}
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\+:


\begin{DoxyItemize}
\item \doxyref{mlpack\+::\+Log}{p.}{classmlpack_1_1Log}, for debugging / informational / warning / fatal output
\item \doxyref{mlpack\+::\+IO}{p.}{classmlpack_1_1IO}, for parsing command line options or other option
\end{DoxyItemize}

Each of those classes are well-\/documented, and that documentation should be consulted for further reference.

First, we\textquotesingle{}ll discuss the logging infrastructure, which is useful for giving output that users can see.\section{Simple Logging Example}\label{iodoc_simplelog}
mlpack has four logging levels\+:


\begin{DoxyItemize}
\item Log\+::\+Debug
\item Log\+::\+Info
\item Log\+::\+Warn
\item Log\+::\+Fatal
\end{DoxyItemize}

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 {\ttfamily --verbose} (or {\ttfamily -\/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 {\ttfamily int} {\ttfamily main()}, we use {\ttfamily static} {\ttfamily void} {\ttfamily mlpack\+Main()}. This is because the automatic binding generator (see \doxyref{mlpack automatic bindings to other languages}{p.}{bindings}) will set up the environment and once that is done, it will call {\ttfamily mlpack\+Main()}.


\begin{DoxyCode}
\textcolor{preprocessor}{#include <mlpack/core.hpp>}
\textcolor{preprocessor}{#include <mlpack/core/util/io.hpp>}
\textcolor{comment}{// This definition below means we will only compile for the command line.}
\textcolor{preprocessor}{#define BINDING\_TYPE BINDING\_TYPE\_CLI}
\textcolor{preprocessor}{#include <mlpack/core/util/mlpack_main.hpp>}

\textcolor{keyword}{using namespace }mlpack;

\textcolor{keyword}{static} \textcolor{keywordtype}{void} mlpackMain()
\{
  Log::Debug << \textcolor{stringliteral}{"Compiled with debugging symbols."} << std::endl;

  Log::Info << \textcolor{stringliteral}{"Some test informational output."} << std::endl;

  Log::Warn << \textcolor{stringliteral}{"A warning!"} << std::endl;

  Log::Fatal << \textcolor{stringliteral}{"Program has crashed."} << std::endl;

  Log::Warn << \textcolor{stringliteral}{"Made it!"} << std::endl;
\}
\end{DoxyCode}


Assuming mlpack is installed on the system and the code above is saved in {\ttfamily test.\+cpp}, this program can be compiled with the following command\+:


\begin{DoxyCode}
$ g++ -o test test.cpp -DDEBUG -g -rdynamic -lmlpack
\end{DoxyCode}


Since we compiled with {\ttfamily -\/\+D\+D\+E\+B\+UG}, if we run the program as below, the following output is shown\+:


\begin{DoxyCode}
$ ./test --verbose
[DEBUG] Compiled with debugging symbols.
[INFO ] Some test informational output.
[WARN ] A warning!
[FATAL] [bt]: (1) /absolute/path/to/file/example.cpp:6: \textcolor{keyword}{function}()
[FATAL] Program has crashed.
terminate called after throwing an instance of \textcolor{stringliteral}{'std::runtime\_error'}
  what():  fatal error; see Log::Fatal output
Aborted
\end{DoxyCode}


The flags {\ttfamily -\/g} and {\ttfamily -\/rdynamic} are only necessary for providing a backtrace. If those flags are not given during compilation, the following output would be shown\+:


\begin{DoxyCode}
$ ./test --verbose
[DEBUG] Compiled with debugging symbols.
[INFO ] Some test informational output.
[WARN ] A warning!
[FATAL] Cannot give backtrace because program was compiled without: -g -rdynamic
[FATAL] For a backtrace, recompile with: -g -rdynamic.
[FATAL] Program has crashed.
terminate called after throwing an instance of \textcolor{stringliteral}{'std::runtime\_error'}
  what():  fatal error; see Log::Fatal output
Aborted
\end{DoxyCode}


The last warning is not reached, because Log\+::\+Fatal terminates the program.

Without debugging symbols (i.\+e. without {\ttfamily -\/g} and {\ttfamily -\/\+D\+D\+E\+B\+UG}) and without --verbose, the following is shown\+:


\begin{DoxyCode}
$ ./test
[WARN ] A warning!
[FATAL] Program has crashed.
terminate called after throwing an instance of \textcolor{stringliteral}{'std::runtime\_error'}
  what():  fatal error; see Log::Fatal output
Aborted
\end{DoxyCode}


These four outputs can be very useful for both providing informational output and debugging output for your mlpack program.\section{Simple I\+O Example}\label{iodoc_simpleio}
Through the \doxyref{mlpack\+::\+IO}{p.}{classmlpack_1_1IO} object, command-\/line parameters can be easily added with the B\+I\+N\+D\+I\+N\+G\+\_\+\+N\+A\+ME, B\+I\+N\+D\+I\+N\+G\+\_\+\+S\+H\+O\+R\+T\+\_\+\+D\+E\+SC, B\+I\+N\+D\+I\+N\+G\+\_\+\+L\+O\+N\+G\+\_\+\+D\+E\+SC, B\+I\+N\+D\+I\+N\+G\+\_\+\+E\+X\+A\+M\+P\+LE, B\+I\+N\+D\+I\+N\+G\+\_\+\+S\+E\+E\+\_\+\+A\+L\+SO, P\+A\+R\+A\+M\+\_\+\+I\+NT, P\+A\+R\+A\+M\+\_\+\+D\+O\+U\+B\+LE, P\+A\+R\+A\+M\+\_\+\+S\+T\+R\+I\+NG, and P\+A\+R\+A\+M\+\_\+\+F\+L\+AG 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.)


\begin{DoxyCode}
\textcolor{preprocessor}{#include <mlpack/core.hpp>}
\textcolor{preprocessor}{#include <mlpack/core/util/io.hpp>}
\textcolor{preprocessor}{#include <mlpack/core/util/mlpack_main.hpp>}

\textcolor{comment}{// Program Name.}
BINDING_NAME(\textcolor{stringliteral}{"Principal Components Analysis"});

\textcolor{comment}{// Short description.}
BINDING_SHORT_DESC(
    \textcolor{stringliteral}{"An implementation of several strategies for principal components analysis "}
    \textcolor{stringliteral}{"(PCA), a common preprocessing step.  Given a dataset and a desired new "}
    \textcolor{stringliteral}{"dimensionality, this can reduce the dimensionality of the data using the "}
    \textcolor{stringliteral}{"linear transformation determined by PCA."});

\textcolor{comment}{// Long description.}
BINDING_LONG_DESC(
    \textcolor{stringliteral}{"This program performs principal components analysis on the given dataset "}
    \textcolor{stringliteral}{"using the exact, randomized, randomized block Krylov, or QUIC SVD method. "}
    \textcolor{stringliteral}{"It will transform the data onto its principal components, optionally "}
    \textcolor{stringliteral}{"performing dimensionality reduction by ignoring the principal components "}
    \textcolor{stringliteral}{"with the smallest eigenvalues."});

\textcolor{comment}{// See also...}
BINDING_SEE_ALSO(\textcolor{stringliteral}{"Principal component analysis on Wikipedia"},
        \textcolor{stringliteral}{"https://en.wikipedia.org/wiki/Principal\_component\_analysis"});
BINDING_SEE_ALSO(\textcolor{stringliteral}{"mlpack::pca::PCA C++ class documentation"},
        \textcolor{stringliteral}{"@doxygen/classmlpack\_1\_1pca\_1\_1PCA.html"}));

\textcolor{comment}{// Parameters for program.}
PARAM_MATRIX_IN_REQ(\textcolor{stringliteral}{"input"}, \textcolor{stringliteral}{"Input dataset to perform PCA on."}, \textcolor{stringliteral}{"i"});
PARAM_MATRIX_OUT(\textcolor{stringliteral}{"output"}, \textcolor{stringliteral}{"Matrix to save modified dataset to."}, \textcolor{stringliteral}{"o"});
PARAM_INT_IN(\textcolor{stringliteral}{"new\_dimensionality"}, \textcolor{stringliteral}{"Desired dimensionality of output dataset."},
    \textcolor{stringliteral}{"d"}, 0);

\textcolor{keyword}{using namespace }mlpack;

\textcolor{keyword}{static} \textcolor{keywordtype}{void} mlpackMain()
\{
  \textcolor{comment}{// Load input dataset.}
  arma::mat& dataset = IO::GetParam<arma::mat>(\textcolor{stringliteral}{"input"});

  \textcolor{keywordtype}{size\_t} newDimension = IO::GetParam<int>(\textcolor{stringliteral}{"new\_dimensionality"});

  ...

  \textcolor{comment}{// Now save the results.}
  \textcolor{keywordflow}{if} (IO::HasParam(\textcolor{stringliteral}{"output"}))
    IO::GetParam<arma::mat>(\textcolor{stringliteral}{"output"}) = std::move(dataset);
\}
\end{DoxyCode}


Documentation is automatically generated using those macros, and when the program is run with --help the following is displayed\+:


\begin{DoxyCode}
$ mlpack\_pca --help
Principal Components Analysis

  This program performs principal components analysis on the given dataset.  It
  will transform the data onto its principal components, optionally performing
  dimensionality reduction by ignoring the principal components with the
  smallest eigenvalues.

Required options:

  --input\_file [string]         Input dataset to perform PCA on.
  --output\_file [string]        Matrix to save modified dataset to.

Options:

  --help (-h)                   Default help info.
  --info [string]               Get help on a specific module or option.
                                Default value \textcolor{stringliteral}{''}.
  --new\_dimensionality [int]    Desired dimensionality of output dataset.
                                Default value 0.
  --verbose (-v)                Display informational messages and the full list
                                of parameters and timers at the end of
                                execution.
\end{DoxyCode}


The \doxyref{mlpack\+::\+IO}{p.}{classmlpack_1_1IO} documentation can be consulted for further and complete documentation. Also useful is to look at other example bindings, found in {\ttfamily src/mlpack/methods/}.