diff --git a/.ci/ci.yaml b/.ci/ci.yaml index 1bb02279e2..f8720cf17c 100644 --- a/.ci/ci.yaml +++ b/.ci/ci.yaml @@ -18,7 +18,7 @@ jobs: CMakeArgs: '-DDEBUG=ON -DPROFILE=OFF -DBUILD_PYTHON_BINDINGS=OFF -DBUILD_JULIA_BINDINGS=OFF -DBUILD_GO_BINDINGS=OFF' Python: python.version: '3.7' - CMakeArgs: '-DDEBUG=OFF -DPROFILE=OFF -DPYTHON_EXECUTABLE=/opt/hostedtoolcache/Python/3.7.7/x64/bin/python3 -DBUILD_GO_BINDINGS=OFF -DBUILD_JULIA_BINDINGS=OFF' + CMakeArgs: '-DDEBUG=OFF -DPROFILE=OFF -DBUILD_PYTHON_BINDINGS=ON -DPYTHON_EXECUTABLE=/usr/bin/python3 -DBUILD_GO_BINDINGS=OFF -DBUILD_JULIA_BINDINGS=OFF' Julia: julia.version: '1.3.0' CMakeArgs: '-DDEBUG=OFF -DPROFILE=OFF -DBUILD_PYTHON_BINDINGS=OFF -DBUILD_JULIA_BINDINGS=ON -DBUILD_GO_BINDINGS=OFF -DJULIA_EXECUTABLE=/opt/julia-1.3.0/bin/julia' @@ -42,7 +42,7 @@ jobs: python.version: '2.7' Python: python.version: '3.7' - CMakeArgs: '-DDEBUG=OFF -DPROFILE=OFF -DBUILD_JULIA_BINDINGS=OFF -DBUILD_GO_BINDINGS=OFF' + CMakeArgs: '-DDEBUG=OFF -DPROFILE=OFF -DBUILD_PYTHON_BINDINGS=ON -DBUILD_JULIA_BINDINGS=OFF -DBUILD_GO_BINDINGS=OFF' Julia: python.version: '2.7' julia.version: '1.3.0' diff --git a/.ci/linux-steps.yaml b/.ci/linux-steps.yaml index 7fd0ab0ab5..13835e9292 100644 --- a/.ci/linux-steps.yaml +++ b/.ci/linux-steps.yaml @@ -22,12 +22,9 @@ steps: echo "##vso[task.setvariable variable=BOOST_ROOT]"$BOOST_ROOT sudo apt-get install -y --allow-unauthenticated libopenblas-dev liblapack-dev g++ libboost1.70-dev libarmadillo-dev xz-utils - sudo apt-get install -y --allow-unauthenticated python3-pip python3-numpy - - sudo /opt/hostedtoolcache/Python/3.7.7/x64/bin/python3 -m pip install "Cython>0.24" - sudo /opt/hostedtoolcache/Python/3.7.7/x64/bin/python3 -m pip install --upgrade --ignore-installed setuptools - sudo /opt/hostedtoolcache/Python/3.7.7/x64/bin/python3 -m pip install pandas + /usr/bin/python3 -m pip install --upgrade pip + /usr/bin/python3 -m pip install --upgrade --ignore-installed setuptools cython pandas if [ 'a$(julia.version)' != 'a' ]; then wget https://julialang-s3.julialang.org/bin/linux/x64/1.3/julia-1.3.0-linux-x86_64.tar.gz diff --git a/CMakeLists.txt b/CMakeLists.txt index 9f092fe0d3..a9e69baef2 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -16,7 +16,6 @@ option(BUILD_CLI_EXECUTABLES "Build command-line executables." ON) option(DISABLE_DOWNLOADS "Disable downloads of dependencies during build." OFF) option(DOWNLOAD_ENSMALLEN "If ensmallen is not found, download it." ON) option(DOWNLOAD_STB_IMAGE "Download stb_image for image loading." ON) -option(BUILD_PYTHON_BINDINGS "Build Python bindings." ON) option(BUILD_GO_SHLIB "Build Go shared library." OFF) if (WIN32) @@ -30,6 +29,15 @@ else () "Compile shared libraries (if OFF, static libraries are compiled)." ON) endif() +# Detect whether the user passed BUILD_PYTHON_BINDINGS in order to determine if +# we should fail if Python isn't found. +if (BUILD_PYTHON_BINDINGS) + set(FORCE_BUILD_PYTHON_BINDINGS ON) +else() + set(FORCE_BUILD_PYTHON_BINDINGS OFF) +endif() +option(BUILD_PYTHON_BINDINGS "Build Python bindings." OFF) + # Detect whether the user passed BUILD_JULIA_BINDINGS in order to determine if # we should fail if Julia isn't found. if (BUILD_JULIA_BINDINGS) diff --git a/HISTORY.md b/HISTORY.md index 211edf81b4..c04b2aeca1 100644 --- a/HISTORY.md +++ b/HISTORY.md @@ -1,5 +1,10 @@ ### mlpack ?.?.? ###### ????-??-?? + * Force CMake to show error when it didn't find Python/modules (#2568). + + * Refactor `ProgramInfo()` to separate out all the different + information (#2558). + * Added Soft Actor-Critic to RL methods (#2487). * Added Categorical DQN to q_networks (#2454). @@ -20,6 +25,10 @@ version of linear regression where the regularization parameter is automatically tuned (#2030). + * Fix incremental training of logistic regression models (#2560). + + * Change default configuration of `BUILD_PYTHON_BINDINGS` to `OFF` (#2575). + ### mlpack 3.3.2 ###### 2020-06-18 * Added Noisy DQN to q_networks (#2446). diff --git a/doc/guide/bindings.hpp b/doc/guide/bindings.hpp index 96e57a01b7..2ef5db763b 100644 --- a/doc/guide/bindings.hpp +++ b/doc/guide/bindings.hpp @@ -19,7 +19,7 @@ The document is split into several sections: - @ref bindings_intro - @ref bindings_code - @ref bindings_general - - @ref bindings_general_program_info + - @ref bindings_general_program_doc - @ref bindings_general_define_params - @ref bindings_general_functions - @ref bindings_general_more @@ -128,12 +128,18 @@ using namespace std; // being used. Note that the macros must have + on either side of them. We // provide some extra references with the "SEE_ALSO()" macro, which is used to // generate documentation for the website. -PROGRAM_INFO("Mean Shift Clustering", - // Short description. + +// Program Name. +BINDING_NAME("Mean Shift Clustering"); + +// Short description. +BINDING_SHORT_DESC( "A fast implementation of mean-shift clustering using dual-tree range " "search. Given a dataset, this uses the mean shift algorithm to produce " - "and return a clustering of the data.", - // Long description. + "and return a clustering of the data."); + +// Long description. +BINDING_LONG_DESC( "This program performs mean shift clustering on the given dataset, storing " "the learned cluster assignments either as a column of labels in the input " "dataset or separately." @@ -147,22 +153,26 @@ PROGRAM_INFO("Mean Shift Clustering", "\n\n" "The output labels may be saved with the " + PRINT_PARAM_STRING("output") + " output parameter and the centroids of each cluster may be saved with the" - " " + PRINT_PARAM_STRING("centroid") + " output parameter." - "\n\n" + " " + PRINT_PARAM_STRING("centroid") + " output parameter."); + +// Example. +BINDING_EXAMPLE( "For example, to run mean shift clustering on the dataset " + PRINT_DATASET("data") + " and store the centroids to " + PRINT_DATASET("centroids") + ", the following command may be used: " "\n\n" + - PRINT_CALL("mean_shift", "input", "data", "centroid", "centroids"), - SEE_ALSO("@kmeans", "#kmeans"), - SEE_ALSO("@dbscan", "#dbscan"), - SEE_ALSO("Mean shift on Wikipedia", - "https://en.wikipedia.org/wiki/Mean_shift"), - SEE_ALSO("Mean Shift, Mode Seeking, and Clustering (pdf)", + PRINT_CALL("mean_shift", "input", "data", "centroid", "centroids")); + +// See also... +BINDING_SEE_ALSO("@kmeans", "#kmeans"); +BINDING_SEE_ALSO("@dbscan", "#dbscan"); +BINDING_SEE_ALSO("Mean shift on Wikipedia", + "https://en.wikipedia.org/wiki/Mean_shift"); +BINDING_SEE_ALSO("Mean Shift, Mode Seeking, and Clustering (pdf)", "http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.510.1222" - "&rep=rep1&type=pdf"), - SEE_ALSO("mlpack::mean_shift::MeanShift C++ class documentation", - "@doxygen/classmlpack_1_1meanshift_1_1MeanShift.html")); + "&rep=rep1&type=pdf"); +BINDING_SEE_ALSO("mlpack::mean_shift::MeanShift C++ class documentation", + "@doxygen/classmlpack_1_1meanshift_1_1MeanShift.html"); // Define parameters for the executable. @@ -228,9 +238,10 @@ void mlpackMain() @endcode We can see that we have defined the basic program information in the -@c PROGRAM_INFO() macro. This is, for instance, what is displayed to describe -the binding if the user passed the \--help option for a -command-line program. +@c BINDING_NAME(), @c BINDING_SHORT_DESC(), @c BINDING_LONG_DESC(), +@c BINDING_EXAMPLE() and @c BINDING_SEE_ALSO() macros. This is, for instance, +what is displayed to describe the binding if the user passed the +\--help option for a command-line program. Then, we define five parameters, three input and two output, that define the data and options that the mean shift clustering will function on. These @@ -247,10 +258,12 @@ whether the parameter is input or output. Some examples: Note that each of these macros may have slightly different syntax. See the links above for further documentation. -In order to write a new binding, then, you simply must write a @c PROGRAM_INFO() -definition of the program with some docuentation, define the input and output -parameters as @c PARAM macros, and then write an @c mlpackMain() function that -actually performs the functionality of the binding. Inside of @c mlpackMain(): +In order to write a new binding, then, you simply must write @c BINDING_NAME(), +@c BINDING_SHORT_DESC(), @c BINDING_LONG_DESC(), @c BINDING_EXAMPLE() and +@c BINDING_SEE_ALSO() definitions of the program with some docuentation, define +the input and output parameters as @c PARAM macros, and then write an +@c mlpackMain() function that actually performs the functionality of the binding. +Inside of @c mlpackMain(): - All input parameters are accessible through @c IO::GetParam("name"). - All output parameters should be set by the end of the function with the @@ -278,15 +291,27 @@ relatively clear how one could use the @c IO functionality along with CMake to add a binding for a new mlpack machine learning method. If it is not clear, then the examples in the following sections should clarify. -@subsection bindings_general_program_info Documenting a program with PROGRAM_INFO() +@subsection bindings_general_program_doc Documenting a program with +@c BINDING_NAME(), @c BINDING_SHORT_DESC(), @c BINDING_LONG_DESC(), +@c BINDING_EXAMPLE() and @c BINDING_SEE_ALSO(). -Any mlpack program should be documented with the @c PROGRAM_INFO() macro, which -is available from the @c header. The macro -is of the form +Any mlpack program should be documented with the @c BINDING_NAME(), +@c BINDING_SHORT_DESC(), @c BINDING_LONG_DESC() , @c BINDING_EXAMPLE() and +@c BINDING_SEE_ALSO() macros, which is available from the +@c header. The macros +are of the form @code -PROGRAM_INFO("program name", "short documentation", "long documentation", - SEE_ALSO("link", "description"), ...) +BINDING_NAME("program name"); +BINDING_SHORT_DESC("This is a short, two-sentence description of what the program does."); +BINDING_LONG_DESC("This is a long description of what the program does." + " It might be many lines long and have lots of details about different options."); +BINDING_EXAMPLE("This contains one example for this particular binding.\n" + + PROGRAM_CALL(...)); +BINDING_EXAMPLE("This contains another example for this particular binding.\n" + + PROGRAM_CALL(...)); +// There could be many of these "see alsos". +BINDING_SEE_ALSO("https://en.wikipedia.org/wiki/Machine_learning"); @endcode The short documentation should be two sentences indicating what the program @@ -368,6 +393,14 @@ Command-line program output (snippet): Python binding output (snippet): The parameter 'shuffle', if set, will shuffle the data before learning. + +Julia binding output (snippet): + + The parameter `shuffle`, if set, will shuffle the data before learning. + +Go binding output (snippet): + + The parameter "Shuffle", if set, will shuffle the data before learning. @endcode @code @@ -383,6 +416,14 @@ Command-line program output (snippet): Python binding output (snippet): The output matrix can be saved with the 'output' output parameter. + +Julia binding output (snippet): + + The output matrix can be saved with the `output` output parameter. + +Go binding output (snippet): + + The output matrix can be saved with the "output" output parameter. @endcode @code @@ -408,12 +449,38 @@ Python binding output (snippet): >>> output = program(input=x) >>> model = output['output_model'] + +Julia binding output (snippet): + + For example, to train a model on the dataset `x` and save the output model to + `model`, the following command can be used: + + julia> model = program(input=x) + +Go binding output (snippet): + + For example, to train a model on the dataset "x" and save the output model to + "model", the following command can be used: + + // Initialize optional parameters for Program(). + param := mlpack.ProgramOptions() + param.Input = x + + model := mlpack.Program(param) @endcode @code Input C++ (full program, 'random_numbers_main.cpp'): - PROGRAM_INFO("Random Numbers", "This program generates random numbers with a " + // Program Name. + BINDING_NAME("Random Numbers"); + + // Short description. + BINDING_SHORT_DESC("An implementation of Random Numbers"); + + // Long description. + BINDING_LONG_DESC( + "This program generates random numbers with a " "variety of nonsensical techniques and example parameters. The input " "dataset, which will be ignored, can be specified with the " + PRINT_PARAM_STRING("input") + " parameter. If you would like to subtract" @@ -425,8 +492,10 @@ Input C++ (full program, 'random_numbers_main.cpp'): "The output random numbers can be saved with the " + PRINT_PARAM_STRING("output") + " output parameter. In addition, a " "randomly generated linear regression model can be saved with the " + - PRINT_PARAM_STRING("output_model") + " output parameter." - "\n\n" + PRINT_PARAM_STRING("output_model") + " output parameter."); + + // Example. + BINDING_EXAMPLE( "For example, to generate 100 random numbers with 3 subtracted from them " "and save the output to " + PRINT_DATASET("rand") + " and the random " "model to " + PRINT_MODEL("rand_lr") + ", use the following " @@ -479,17 +548,66 @@ Python binding output: >>> output = random_numbers(num_values=100, subtract=3) >>> rand = output['output'] >>> rand_lr = output['output_model'] + +Julia binding output: + + Random Numbers + + This program generates random numbers with a variety of nonsensical + techniques and example parameters. The input dataset, which will be + ignored, can be specified with the `input` parameter. If you would like to + subtract values from each number, specify the `subtract` parameter. The + number of random numbers to generate is specified with the `num_values` + parameter. + + The output random numbers can be saved with the `output` output parameter. + In addition, a randomly generated linear regression model can be saved with + the `output_model` output parameter. + + For example, to generate 100 random numbers with 3 subtracted from them and + save the output to `rand` and the random model to `rand_lr`, use the + following command: + + ```julia + julia> rand, rand_lr = random_numbers(num_values=100, subtract=3) + ``` + +Go binding output: + + Random Numbers + + This program generates random numbers with a variety of nonsensical + techniques and example parameters. The input dataset, which will be + ignored, can be specified with the "Input" parameter. If you would like to + subtract values from each number, specify the "Subtract" parameter. The + number of random numbers to generate is specified with the "NumValues" + parameter. + + The output random numbers can be saved with the "output" output parameter. + In addition, a randomly generated linear regression model can be saved with + the "outputModel" output parameter. + + For example, to generate 100 random numbers with 3 subtracted from them and + save the output to "rand" and the random model to "randLr", use the + following command: + + // Initialize optional parameters for RandomNumbers(). + param := mlpack.RandomNumbersOptions() + param.NumValues = 100 + param.Subtract=3 + + rand, randLr := mlpack.RandomNumbers(param) @endcode @subsection bindings_general_define_params Defining parameters for a program -There exist several macros that can be used after a @c PROGRAM_INFO() definition -to define the parameters that can be specified for a given mlpack program. -These macros all have the same general definition: the name of the macro -specifies the type of the parameter, whether or not the parameter is required, -and whether the parameter is an input or output parameter. Then as arguments to -the macro, the name, description, and sometimes the single-character alias and -the default value of the parameter. +There exist several macros that can be used after a @c BINDING_LONG_DESC() and +@c BINDING_EXAMPLE() definition to define the parameters that can be specified +for a given mlpack program. These macros all have the same general definition: +the name of the macro specifies the type of the parameter, whether or not the +parameter is required, and whether the parameter is an input or output parameter. +Then as arguments to the macros, the name, description, and sometimes the +single-character alias and the default value of the parameter. To give a flavor of how these definitions look, the definition @@ -620,10 +738,10 @@ Python interface to the user. mlpack's @c IO module provides a unified abstract interface for getting input from and providing output to users without needing to consider the language (command-line, Python, MATLAB, etc.) that the user is running the program from. -This means that after the @c PROGRAM_INFO() macro and the @c PARAM_*() macros -have been defined, a language-agnostic @c mlpackMain() function can be written. -This function then can perform the actual computation that the entire program is -meant to. +This means that after the @c BINDING_LONG_DESC() and @c BINDING_EXAMPLE() macros +and the @c PARAM_*() macros have been defined, a language-agnostic +@c mlpackMain() function can be written. This function then can perform the +actual computation that the entire program is meant to. Inside of an @c mlpackMain() function, the @c mlpack::IO module can be used to access input parameters and set output parameters. There are two main functions @@ -703,7 +821,8 @@ could be created for the "random_numbers" program from earlier sections. @code #include -// The PROGRAM_INFO() and PARAM_*() definitions should go here: +// BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC() , BINDING_EXAMPLE(), +// BINDING_SEE_ALSO() and PARAM_*() definitions should go here: // ... using namespace mlpack; @@ -759,23 +878,43 @@ This section describes the internal functionality of the IO module and the associated macros. If you are only interested in writing mlpack programs, this section is probably not worth reading. -There are four main components involved with mlpack bindings: +There are eight main components involved with mlpack bindings: - the IO module, a singleton class that stores parameter information - the mlpackMain() function that defines the functionality of the binding - - the PROGRAM_INFO() macro that defines the binding name and documentation + - the BINDING_NAME() macro that defines the binding name + - the BINDING_SHORT_DESC() macro that defines the short description + - the BINDING_LONG_DESC() macro that defines the long description + - (optional) the BINDING_EXAMPLE() macro that defines example usages + - (optional) the BINDING_SEE_ALSO() macro that defines "see also" links - the PARAM_*() macros that define parameters for the binding The mlpack::IO module is a singleton class that stores, at runtime, the binding name, the documentation, and the parameter information and values. In order to do this, each parameter and the program documentation must make themselves known -to the IO singleton. This is accomplished by having the @c PROGRAM_INFO() and -@c PARAM_*() macros declare global variables that, in their constructors, -register themselves with the IO singleton. +to the IO singleton. This is accomplished by having the @c BINDING_NAME(), +@c BINDING_SHORT_DESC(), @c BINDING_LONG_DESC(), @c BINDING_EXAMPLE(), +@c BINDING_SEE_ALSO() and @c PARAM_*() macros declare global variables that, +in their constructors, register themselves with the IO singleton. -The @c PROGRAM_INFO() macro declares an object of type mlpack::util::ProgramDoc. -The @c ProgramDoc class constructor calls IO::RegisterProgramDoc() in order to -register the given program name and documentation. +The @c BINDING_NAME() macro declares an object of type mlpack::util::ProgramName. +The @c BINDING_SHORT_DESC() macro declares an object of type +mlpack::util::ShortDescription. +The @c BINDING_LONG_DESC() macro declares an object of type +mlpack::util::LongDescription. +The @c BINDING_EXAMPLE() macro declares an object of type mlpack::util::Example. +The @c BINDING_SEE_ALSO() macro declares an object of type +mlpack::util::SeeAlso. +The @c ProgramName class constructor calls IO::RegisterProgramName() in order to +register the given program name. +The @c ShortDescription class constructor calls IO::RegisterShortDescription() in order to +register the given short description. +The @c LongDescription class constructor calls IO::RegisterLongDescription() in order to +register the given long description. +The @c Example class constructor calls IO::RegisterExample() in order to +register the given example. +The @c SeeAlso class constructor calls IO::RegisterSeeAlso() in order to +register the given see-also link. The @c PARAM_*() macros declare an object that will, in its constructor, call IO::Add() to register that parameter with the IO singleton. The specific type @@ -875,7 +1014,8 @@ binding: - The options defined by @c PARAM_*() macros are of type mlpack::bindings::cli::CLIOption. - - The parameter and value printing macros for @c PROGRAM_INFO() are set: + - The parameter and value printing macros for @c BINDING_LONG_DESC() + and BINDING_EXAMPLE() are set: * The @c PRINT_PARAM_STRING() macro is defined as mlpack::bindings::cli::ParamString(). * The @c PRINT_DATASET() macro is defined as @@ -1047,9 +1187,10 @@ individually if you like). The file the name of the program and the @c *_main.cpp file to include correctly, then the @c mlpack::bindings::python::PrintPYX() function is called by the program. The @c PrintPYX() function uses the parameters that have been set in the IO -singleton by the @c PROGRAM_INFO() and @c PARAM_*() macros in order to actually -print a fully-working .pyx file that can be compiled. The file has several -sections: +singleton by the @c BINDING_NAME(), @c BINDING_SHORT_DESC(), +@c BINDING_LONG_DESC(), @c BINDING_EXAMPLE(), @c BINDING_SEE_ALSO() and +@c PARAM_*() macros in order to actually print a fully-working .pyx file that +can be compiled. The file has several sections: - Python imports (numpy/pandas/cython/etc.) - Cython imports of C++ utility functions and Armadillo functionality diff --git a/doc/guide/iodoc.hpp b/doc/guide/iodoc.hpp index 3282268f88..b60f6fc937 100644 --- a/doc/guide/iodoc.hpp +++ b/doc/guide/iodoc.hpp @@ -120,7 +120,8 @@ and debugging output for your mlpack program. @section simpleio Simple IO Example Through the mlpack::IO object, command-line parameters can be easily added -with the PROGRAM_INFO, PARAM_INT, PARAM_DOUBLE, PARAM_STRING, and PARAM_FLAG +with the BINDING_NAME, BINDING_SHORT_DESC, BINDING_LONG_DESC, BINDING_EXAMPLE, +BINDING_SEE_ALSO, 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. @@ -131,23 +132,28 @@ Here is a sample use of those macros, extracted from methods/pca/pca_main.cpp. #include #include -// Document program. -PROGRAM_INFO("Principal Components Analysis", - // Short description. +// Program Name. +BINDING_NAME("Principal Components Analysis"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of several strategies for principal components analysis " "(PCA), a common preprocessing step. Given a dataset and a desired new " "dimensionality, this can reduce the dimensionality of the data using the " - "linear transformation determined by PCA.", - // Long description. + "linear transformation determined by PCA."); + +// Long description. +BINDING_LONG_DESC( "This program performs principal components analysis on the given dataset " "using the exact, randomized, randomized block Krylov, or QUIC SVD method. " "It will transform the data onto its principal components, optionally " "performing dimensionality reduction by ignoring the principal components " - "with the smallest eigenvalues." - // "See also" section for generated documentation. - SEE_ALSO("Principal component analysis on Wikipedia", - "https://en.wikipedia.org/wiki/Principal_component_analysis"), - SEE_ALSO("mlpack::pca::PCA C++ class documentation", + "with the smallest eigenvalues."); + +// See also... +BINDING_SEE_ALSO("Principal component analysis on Wikipedia", + "https://en.wikipedia.org/wiki/Principal_component_analysis"); +BINDING_SEE_ALSO("mlpack::pca::PCA C++ class documentation", "@doxygen/classmlpack_1_1pca_1_1PCA.html")); // Parameters for program. diff --git a/src/mlpack/bindings/cli/cli_option.hpp b/src/mlpack/bindings/cli/cli_option.hpp index f09f324ea0..eeebc2d7cc 100644 --- a/src/mlpack/bindings/cli/cli_option.hpp +++ b/src/mlpack/bindings/cli/cli_option.hpp @@ -3,7 +3,7 @@ * @author Matthew Amidon * * Definition of the Option class, which is used to define parameters which are - * used by CLI. The ProgramDoc class also resides here. + * used by CLI. * * mlpack is free software; you may redistribute it and/or modify it under the * terms of the 3-clause BSD license. You should have received a copy of the @@ -164,35 +164,6 @@ class CLIOption } }; -/** - * A static object whose constructor registers program documentation with the - * CLI class. This should not be used outside of CLI itself, and you should use - * the PROGRAM_INFO() macro to declare these objects. Only one ProgramDoc - * object should ever exist. - * - * @see core/util/io.hpp, mlpack::IO - */ -class ProgramDoc -{ - public: - /** - * Construct a ProgramDoc object. When constructed, it will register itself - * with IO. - * - * @param programName Short string representing the name of the program. - * @param documentation Long string containing documentation on how to use the - * program and what it is. No newline characters are necessary; this is - * taken care of by IO later. - */ - ProgramDoc(const std::string& programName, - const std::string& documentation); - - //! The name of the program. - std::string programName; - //! Documentation for what the program does. - std::string documentation; -}; - } // namespace cli } // namespace bindings } // namespace mlpack diff --git a/src/mlpack/bindings/cli/print_doc_functions.hpp b/src/mlpack/bindings/cli/print_doc_functions.hpp index 3b027f8720..1f7e9390bb 100644 --- a/src/mlpack/bindings/cli/print_doc_functions.hpp +++ b/src/mlpack/bindings/cli/print_doc_functions.hpp @@ -102,8 +102,9 @@ inline std::string ProgramCall(const std::string& programName); /** * Print what a user would type to invoke the given option name. Note that the * name *must* exist in the CLI module. (Note that because of the way - * ProgramInfo is structured, this doesn't mean that all of the PARAM_*() - * declarataions need to come before the PROGRAM_INFO() declaration.) + * BINDING_LONG_DESC() and BINDING_EXAMPLE() is structured, this doesn't mean + * that all of the PARAM_*() declarataions need to come before + * BINDING_LONG_DESC() and BINDING_EXAMPLE() declaration.) */ inline std::string ParamString(const std::string& paramName); diff --git a/src/mlpack/bindings/cli/print_doc_functions_impl.hpp b/src/mlpack/bindings/cli/print_doc_functions_impl.hpp index fbfa22c33b..68339e5912 100644 --- a/src/mlpack/bindings/cli/print_doc_functions_impl.hpp +++ b/src/mlpack/bindings/cli/print_doc_functions_impl.hpp @@ -138,8 +138,8 @@ std::string ProcessOptions(const std::string& paramName, else { throw std::runtime_error("Unknown parameter '" + paramName + "' " + - "encountered while assembling documentation! Check PROGRAM_INFO() " + - "declaration."); + "encountered while assembling documentation! Check BINDING_LONG_DESC()" + + " and BINDING_EXAMPLE() declaration."); } std::string rest = ProcessOptions(args...); @@ -229,8 +229,9 @@ inline std::string ProgramCall(const std::string& programName) /** * Print what a user would type to invoke the given option name. Note that the * name *must* exist in the CLI module. (Note that because of the way - * ProgramInfo is structured, this doesn't mean that all of the PARAM_*() - * declarataions need to come before the PROGRAM_INFO() declaration.) + * BINDING_LONG_DESC() and BINDING_EXAMPLE() is structured, this doesn't mean + * that all of the PARAM_*() declarataions need to come before + * BINDING_LONG_DESC() and BINDING_EXAMPLE() declaration.) */ inline std::string ParamString(const std::string& paramName) { @@ -252,7 +253,7 @@ inline std::string ParamString(const std::string& paramName) else { throw std::runtime_error("Parameter '" + paramName + "' not known! Check " - "PROGRAM_INFO() definition."); + "BINDING_LONG_DESC() and BINDING_EXAMPLE() definition."); } } diff --git a/src/mlpack/bindings/cli/print_help.cpp b/src/mlpack/bindings/cli/print_help.cpp index 5cfa1bf57e..a1cf44089f 100644 --- a/src/mlpack/bindings/cli/print_help.cpp +++ b/src/mlpack/bindings/cli/print_help.cpp @@ -25,8 +25,7 @@ void PrintHelp(const std::string& param) std::string usedParam = param; std::map& parameters = IO::Parameters(); const std::map& aliases = IO::Aliases(); - util::ProgramDoc& docs = *IO::GetSingleton().doc; - + util::BindingDetails& bindingDetails = IO::GetSingleton().doc; // If we pass a single param, alias it if necessary. if (usedParam.length() == 1 && aliases.count(usedParam[0])) usedParam = aliases.at(usedParam[0]); @@ -64,11 +63,16 @@ void PrintHelp(const std::string& param) } // Print out the descriptions. - if (docs.programName != "") + if (bindingDetails.programName != "") { - std::cout << docs.programName << std::endl << std::endl; - std::cout << " " << util::HyphenateString(docs.documentation(), 2) - << std::endl << std::endl; + std::cout << bindingDetails.programName << std::endl << std::endl; + std::cout << " " << util::HyphenateString(bindingDetails.longDescription(), + 2) << std::endl << std::endl; + for (size_t j = 0; j < bindingDetails.example.size(); ++j) + { + std::cout << " " << util::HyphenateString(bindingDetails.example[j](), 2) + << std::endl << std::endl; + } } else std::cout << "[undocumented program]" << std::endl << std::endl; diff --git a/src/mlpack/bindings/go/CMakeLists.txt b/src/mlpack/bindings/go/CMakeLists.txt index b35ae1bc41..e769966791 100644 --- a/src/mlpack/bindings/go/CMakeLists.txt +++ b/src/mlpack/bindings/go/CMakeLists.txt @@ -16,34 +16,33 @@ if (NOT BUILD_GO_BINDINGS) endif () if (BUILD_GO_BINDINGS) + + find_package(Go 1.11.0) + if (NOT GO_FOUND) + set(GO_NOT_FOUND_MSG "${GO_NOT_FOUND_MSG}\n - Go") + endif () + find_package(Gonum) + if (NOT GONUM_FOUND) + set(GO_NOT_FOUND_MSG "${GO_NOT_FOUND_MSG}\n - Gonum") + endif () + ## We need to check here if Golang is even available. Although actually ## technically, I'm not sure if we even need to know! For the tests though we ## do. So it's probably a good idea to check. if (FORCE_BUILD_GO_BINDINGS) - find_package(Go 1.11.0) - find_package(Gonum) if (NOT GO_FOUND OR NOT GONUM_FOUND) unset(BUILD_GO_BINDINGS CACHE) set(BUILD_GO_SHLIB OFF) - message(FATAL_ERROR "Go or Gonum not found; unable to build Go bindings!") + message(FATAL_ERROR "\nCould not Build Go Bindings; the following modules are not available: ${GO_NOT_FOUND_MSG}") endif() else () - find_package(Go 1.11.0) - find_package(Gonum) if (NOT GO_FOUND OR NOT GONUM_FOUND) unset(BUILD_GO_BINDINGS CACHE) set(BUILD_GO_SHLIB OFF) + not_found_return("Not building Go bindings; the following modules are not available: ${GO_NOT_FOUND_MSG}") endif() endif () - if (NOT GO_FOUND) - not_found_return("Go not found; not building Go bindings.") - endif () - - if (NOT GONUM_FOUND) - not_found_return("Gonum not found; not building Go bindings.") - endif () - add_custom_target(go) # All the bindings will build under "src/mlpack.org/v1/mlpack"; So if user build diff --git a/src/mlpack/bindings/go/generate_go.cpp.in b/src/mlpack/bindings/go/generate_go.cpp.in index 5a07bc5573..0e75e9c4cd 100644 --- a/src/mlpack/bindings/go/generate_go.cpp.in +++ b/src/mlpack/bindings/go/generate_go.cpp.in @@ -45,5 +45,5 @@ int main(int /* argc */, char** /* argv */) // programName is defined in mlpack_main.hpp. IO::RestoreSettings(programName); - PrintGo(*IO::GetSingleton().doc, "${PROGRAM_NAME}"); + PrintGo(IO::GetSingleton().doc, "${PROGRAM_NAME}"); } diff --git a/src/mlpack/bindings/go/print_doc_functions_impl.hpp b/src/mlpack/bindings/go/print_doc_functions_impl.hpp index 80971f6fda..eb7c508e38 100644 --- a/src/mlpack/bindings/go/print_doc_functions_impl.hpp +++ b/src/mlpack/bindings/go/print_doc_functions_impl.hpp @@ -154,8 +154,8 @@ std::string PrintOptionalInputs(const std::string& paramName, { // Unknown parameter! throw std::runtime_error("Unknown parameter '" + paramName + "' " + - "encountered while assembling documentation! Check PROGRAM_INFO() " + - "declaration."); + "encountered while assembling documentation! Check BINDING_LONG_DESC()" + + " and BINDING_EXAMPLE() declaration."); } // Continue recursion. @@ -211,8 +211,8 @@ std::string PrintInputOptions(const std::string& paramName, { // Unknown parameter! throw std::runtime_error("Unknown parameter '" + paramName + "' " + - "encountered while assembling documentation! Check PROGRAM_INFO() " + - "declaration."); + "encountered while assembling documentation! Check BINDING_LONG_DESC()" + + " and BINDING_EXAMPLE() declaration."); } // Continue recursion. @@ -256,8 +256,8 @@ void GetOptions( { // Unknown parameter! throw std::runtime_error("Unknown parameter '" + paramName + "' " + - "encountered while assembling documentation! Check PROGRAM_INFO() " + - "declaration."); + "encountered while assembling documentation! Check BINDING_LONG_DESC()" + + " and BINDING_EXAMPLE() declaration."); } } diff --git a/src/mlpack/bindings/go/print_go.cpp b/src/mlpack/bindings/go/print_go.cpp index 2d9e19c421..e2c0c9ee27 100644 --- a/src/mlpack/bindings/go/print_go.cpp +++ b/src/mlpack/bindings/go/print_go.cpp @@ -27,14 +27,14 @@ namespace go { * Given a list of parameter definition and program documentation, print a * generated .go file to stdout. * - * @param programInfo Documentation for the program. + * @param doc Documentation for the program. * @param functionName Name of the function (i.e. "pca"). */ -void PrintGo(const util::ProgramDoc& programInfo, - const std::string& functionName) +void PrintGo(const util::BindingDetails& doc, + const std::string& functionName) { // Restore parameters. - IO::RestoreSettings(programInfo.programName); + IO::RestoreSettings(doc.programName); std::map& parameters = IO::Parameters(); typedef std::map::iterator ParamIter; @@ -124,8 +124,15 @@ void PrintGo(const util::ProgramDoc& programInfo, // Print the comment describing the function and its parameters. cout << "/*" << endl; - cout << " " << HyphenateString(programInfo.documentation(), 2) << endl; - cout << endl << endl; + cout << " " << HyphenateString(doc.longDescription(), 2) << endl << endl; + + // Print the examples. + for (size_t j = 0; j < doc.example.size(); ++j) + { + cout << " " << util::HyphenateString(doc.example[j](), 2) << endl << endl; + } + + // Next, print information on the input options. cout << " Input parameters:" << endl; cout << endl; for (size_t i = 0; i < inputOptions.size(); ++i) @@ -216,8 +223,7 @@ void PrintGo(const util::ProgramDoc& programInfo, cout << " " << "disableVerbose()" << endl; // Restore the parameters. - cout << " " << "restoreSettings(\"" << programInfo.programName - << "\")" << endl; + cout << " " << "restoreSettings(\"" << doc.programName << "\")" << endl; cout << endl; // Do any input processing. diff --git a/src/mlpack/bindings/go/print_go.hpp b/src/mlpack/bindings/go/print_go.hpp index 4b6bfdbed6..d2ce7161de 100644 --- a/src/mlpack/bindings/go/print_go.hpp +++ b/src/mlpack/bindings/go/print_go.hpp @@ -22,11 +22,10 @@ namespace go { /** * Given a list of parameter definition and program documentation, print a * generated .go file to stdout. - * - * @param programInfo Documentation for the program. + * @param doc Documentation for the program. * @param functionName Name of the function (i.e. "pca"). */ -void PrintGo(const util::ProgramDoc& programInfo, +void PrintGo(const util::BindingDetails& doc, const std::string& functionName); diff --git a/src/mlpack/bindings/go/tests/CMakeLists.txt b/src/mlpack/bindings/go/tests/CMakeLists.txt index b4a1b754dc..e97aa461c9 100644 --- a/src/mlpack/bindings/go/tests/CMakeLists.txt +++ b/src/mlpack/bindings/go/tests/CMakeLists.txt @@ -3,7 +3,7 @@ add_go_binding(test_go_binding) if (BUILD_GO_BINDINGS) add_test(NAME go_binding_test - COMMAND go test -v ${CMAKE_CURRENT_SOURCE_DIR}/go_binding_test.go + COMMAND ${GO_EXECUTABLE} test -v ${CMAKE_CURRENT_SOURCE_DIR}/go_binding_test.go WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/src/mlpack/bindings/go/src/mlpack.org/v1/mlpack/) set_tests_properties(go_binding_test PROPERTIES ENVIRONMENT "GOPATH=$ENV{GOPATH}:${CMAKE_BINARY_DIR}/src/mlpack/bindings/go/; diff --git a/src/mlpack/bindings/go/tests/test_go_binding_main.cpp b/src/mlpack/bindings/go/tests/test_go_binding_main.cpp index e255f3345e..3aeb255906 100644 --- a/src/mlpack/bindings/go/tests/test_go_binding_main.cpp +++ b/src/mlpack/bindings/go/tests/test_go_binding_main.cpp @@ -18,9 +18,16 @@ using namespace std; using namespace mlpack; using namespace mlpack::kernel; -PROGRAM_INFO("Golang binding test", - "A simple program to test Golang binding functionality.", - "A simple program to test Golang binding functionality. You can build " +// Program Name. +BINDING_NAME("Golang binding test"); + +// Short description. +BINDING_SHORT_DESC( + "A simple program to test Go binding functionality."); + +// Long description. +BINDING_LONG_DESC( + "A simple program to test Go binding functionality. You can build " "mlpack with the BUILD_TESTS option set to off, and this binding will " "no longer be built."); diff --git a/src/mlpack/bindings/julia/generate_jl.cpp.in b/src/mlpack/bindings/julia/generate_jl.cpp.in index 289342f7a7..8dbd38470c 100644 --- a/src/mlpack/bindings/julia/generate_jl.cpp.in +++ b/src/mlpack/bindings/julia/generate_jl.cpp.in @@ -35,5 +35,5 @@ int main(int /* argc */, char** /* argv */) // programName is defined in mlpack_main.hpp. IO::RestoreSettings(programName); - PrintJL(*IO::GetSingleton().doc, "${NAME}", "${MLPACK_JL_LIB_SUFFIX}"); + PrintJL(IO::GetSingleton().doc, "${NAME}", "${MLPACK_JL_LIB_SUFFIX}"); } diff --git a/src/mlpack/bindings/julia/print_doc_functions_impl.hpp b/src/mlpack/bindings/julia/print_doc_functions_impl.hpp index 2c1ef7fe9f..3e8b69b845 100644 --- a/src/mlpack/bindings/julia/print_doc_functions_impl.hpp +++ b/src/mlpack/bindings/julia/print_doc_functions_impl.hpp @@ -144,8 +144,8 @@ inline std::string CreateInputArguments(const std::string& paramName, { // Unknown parameter! throw std::runtime_error("Unknown parameter '" + paramName + "' " + - "encountered while assembling documentation! Check PROGRAM_INFO() " + - "declaration."); + "encountered while assembling documentation! Check BINDING_LONG_DESC()" + + " and BINDING_EXAMPLE() declaration."); } } @@ -223,8 +223,8 @@ inline void GetOptions( { // Unknown parameter! throw std::runtime_error("Unknown parameter '" + paramName + "' " + - "encountered while assembling documentation! Check PROGRAM_INFO() " + - "declaration."); + "encountered while assembling documentation! Check BINDING_LONG_DESC()" + + " and BINDING_EXAMPLE() declaration."); } } diff --git a/src/mlpack/bindings/julia/print_jl.cpp b/src/mlpack/bindings/julia/print_jl.cpp index bc68a8fc83..5bf6eb26a9 100644 --- a/src/mlpack/bindings/julia/print_jl.cpp +++ b/src/mlpack/bindings/julia/print_jl.cpp @@ -15,7 +15,7 @@ #include -using namespace mlpack; +using namespace mlpack::util; using namespace std; namespace mlpack { @@ -27,12 +27,12 @@ extern std::string programName; /** * Print the code for a .jl binding for an mlpack program to stdout. */ -void PrintJL(const util::ProgramDoc& programInfo, +void PrintJL(const util::BindingDetails& doc, const string& functionName, const std::string& mlpackJuliaLibSuffix) { // Restore parameters. - IO::RestoreSettings(programInfo.programName); + IO::RestoreSettings(doc.programName); map& parameters = IO::Parameters(); typedef map::iterator ParamIter; @@ -168,10 +168,15 @@ void PrintJL(const util::ProgramDoc& programInfo, cout << endl; // Next print the description. - cout << util::HyphenateString(programInfo.documentation(), 0) << endl; + cout << HyphenateString(doc.longDescription(), 0) << endl << endl; + + // Next print the examples. + for (size_t j = 0; j < doc.example.size(); ++j) + { + cout << util::HyphenateString(doc.example[j](), 0) << endl << endl; + } // Next, print information on the input options. - cout << endl; cout << "# Arguments" << endl; cout << endl; diff --git a/src/mlpack/bindings/julia/print_jl.hpp b/src/mlpack/bindings/julia/print_jl.hpp index 39b84295d2..5e73f590ff 100644 --- a/src/mlpack/bindings/julia/print_jl.hpp +++ b/src/mlpack/bindings/julia/print_jl.hpp @@ -21,7 +21,7 @@ namespace julia { /** * Print the code for a .jl binding for an mlpack program to stdout. */ -void PrintJL(const util::ProgramDoc& programInfo, +void PrintJL(const util::BindingDetails& doc, const std::string& functionName, const std::string& mlpackJuliaLibSuffix); diff --git a/src/mlpack/bindings/julia/tests/test_julia_binding_main.cpp b/src/mlpack/bindings/julia/tests/test_julia_binding_main.cpp index a91d6e0f6a..5ba385cf2b 100644 --- a/src/mlpack/bindings/julia/tests/test_julia_binding_main.cpp +++ b/src/mlpack/bindings/julia/tests/test_julia_binding_main.cpp @@ -18,8 +18,15 @@ using namespace std; using namespace mlpack; using namespace mlpack::kernel; -PROGRAM_INFO("Julia binding test", - "A simple program to test Julia binding functionality.", +// Program Name. +BINDING_NAME("Julia binding test"); + +// Short description. +BINDING_SHORT_DESC( + "A simple program to test Julia binding functionality."); + +// Long description. +BINDING_LONG_DESC( "A simple program to test Julia binding functionality. You can build " "mlpack with the BUILD_TESTS option set to off, and this binding will " "no longer be built."); diff --git a/src/mlpack/bindings/markdown/binding_info.cpp b/src/mlpack/bindings/markdown/binding_info.cpp index e76ee2eb39..eed8e2098a 100644 --- a/src/mlpack/bindings/markdown/binding_info.cpp +++ b/src/mlpack/bindings/markdown/binding_info.cpp @@ -17,7 +17,8 @@ namespace mlpack { namespace bindings { namespace markdown { -util::ProgramDoc& BindingInfo::GetProgramDoc(const std::string& bindingName) +util::BindingDetails& BindingInfo::GetBindingDetails( + const std::string& bindingName) { if (GetSingleton().map.count(bindingName) == 0) { @@ -28,14 +29,6 @@ util::ProgramDoc& BindingInfo::GetProgramDoc(const std::string& bindingName) return GetSingleton().map.at(bindingName); } - -//! Register a ProgramDoc object with the given bindingName. -void BindingInfo::RegisterProgramDoc(const std::string& bindingName, - const util::ProgramDoc& programDoc) -{ - GetSingleton().map[bindingName] = programDoc; -} - //! Get or modify the current language (don't set it to something invalid!). std::string& BindingInfo::Language() { diff --git a/src/mlpack/bindings/markdown/binding_info.hpp b/src/mlpack/bindings/markdown/binding_info.hpp index b93738b26e..319bb0bcac 100644 --- a/src/mlpack/bindings/markdown/binding_info.hpp +++ b/src/mlpack/bindings/markdown/binding_info.hpp @@ -4,7 +4,7 @@ * * This file defines the BindingInfo singleton class that is used specifically * for the Markdown bindings to map from a binding name (i.e. "knn") to - * multiple ProgramDoc objects, which are then used to generate the + * multiple documentation objects, which are then used to generate the * documentation. * * mlpack is free software; you may redistribute it and/or modify it under the @@ -16,7 +16,7 @@ #define MLPACK_BINDINGS_MARKDOWN_BINDING_NAME_HPP #include -#include +#include namespace mlpack { namespace bindings { @@ -24,31 +24,28 @@ namespace markdown { /** * The BindingInfo class is used by the Markdown documentation generator to - * store multiple ProgramDoc objects, indexed by both the binding name (i.e. + * store multiple documentation objects, indexed by both the binding name (i.e. * "knn") and the language (i.e. "cli"). */ class BindingInfo { public: - //! Return a ProgramDoc object for a given bindingName. - static util::ProgramDoc& GetProgramDoc(const std::string& bindingName); - - //! Register a ProgramDoc object with the given bindingName. - static void RegisterProgramDoc(const std::string& bindingName, - const util::ProgramDoc& programDoc); + //! Return a BindingDetails object for a given bindingName. + static util::BindingDetails& GetBindingDetails( + const std::string& bindingName); //! Get or modify the current language (don't set it to something invalid!). static std::string& Language(); - private: - //! Private constructor, so that only one instance can be created. - BindingInfo() { } - //! Get the singleton. static BindingInfo& GetSingleton(); - //! Internally-held map for mapping a binding name to a ProgramDoc name. - std::unordered_map map; + //! Internally-held map for mapping a binding name to a BindingDetails. + std::unordered_map map; + + private: + //! Private constructor, so that only one instance can be created. + BindingInfo() { } //! Holds the name of the language that we are currently printing. This is //! modified before printing the documentation, and then used by diff --git a/src/mlpack/bindings/markdown/generate_markdown.binding.cpp.in b/src/mlpack/bindings/markdown/generate_markdown.binding.cpp.in index b6ac08952a..a6286faeab 100644 --- a/src/mlpack/bindings/markdown/generate_markdown.binding.cpp.in +++ b/src/mlpack/bindings/markdown/generate_markdown.binding.cpp.in @@ -12,7 +12,7 @@ * http://www.opensource.org/licenses/BSD-3-Clause for more information. */ -#define BINDING_NAME "${BINDING}" +#define MARKDOWN_BINDING_NAME "${BINDING}" #include #include "generate_markdown.${BINDING}.hpp" diff --git a/src/mlpack/bindings/markdown/print_doc_functions.hpp b/src/mlpack/bindings/markdown/print_doc_functions.hpp index 35e60e0934..c122339b95 100644 --- a/src/mlpack/bindings/markdown/print_doc_functions.hpp +++ b/src/mlpack/bindings/markdown/print_doc_functions.hpp @@ -88,8 +88,9 @@ inline std::string ProgramCall(const std::string& programName); /** * Print what a user would type to invoke the given option name. Note that the * name *must* exist in the IO module. (Note that because of the way - * ProgramInfo is structured, this doesn't mean that all of the PARAM_*() - * declarataions need to come before the PROGRAM_INFO() declaration.) + * BINDING_LONG_DESC() and BINDING_EXAMPLE() is structured, this doesn't mean + * that all of the PARAM_*() declarataions need to come before + * BINDING_LONG_DESC() and BINDING_EXAMPLE() declaration.) */ inline std::string ParamString(const std::string& paramName); diff --git a/src/mlpack/bindings/markdown/print_doc_functions_impl.hpp b/src/mlpack/bindings/markdown/print_doc_functions_impl.hpp index da4718487a..968b30486b 100644 --- a/src/mlpack/bindings/markdown/print_doc_functions_impl.hpp +++ b/src/mlpack/bindings/markdown/print_doc_functions_impl.hpp @@ -596,8 +596,9 @@ inline std::string ProgramCall(const std::string& programName) /** * Print what a user would type to invoke the given option name. Note that the * name *must* exist in the CLI module. (Note that because of the way - * ProgramInfo is structured, this doesn't mean that all of the PARAM_*() - * declarataions need to come before the PROGRAM_INFO() declaration.) + * BINDING_LONG_DESC() and BINDING_EXAMPLE() is structured, this doesn't mean + * that all of the PARAM_*() declarataions need to come before + * BINDING_LONG_DESC() and BINDING_EXAMPLE() declaration.) */ inline std::string ParamString(const std::string& paramName) { diff --git a/src/mlpack/bindings/markdown/print_docs.cpp b/src/mlpack/bindings/markdown/print_docs.cpp index 2ffacfd6cb..5d8a55e140 100644 --- a/src/mlpack/bindings/markdown/print_docs.cpp +++ b/src/mlpack/bindings/markdown/print_docs.cpp @@ -12,7 +12,7 @@ #include "print_docs.hpp" #include -#include +#include #include "binding_info.hpp" #include "print_doc_functions.hpp" @@ -45,7 +45,7 @@ void PrintHeaders(const std::string& bindingName, void PrintDocs(const std::string& bindingName, const vector& languages) { - ProgramDoc& programDoc = BindingInfo::GetProgramDoc(bindingName); + BindingDetails& doc = BindingInfo::GetBindingDetails(bindingName); IO::RestoreSettings(bindingName); @@ -64,7 +64,7 @@ void PrintDocs(const std::string& bindingName, // Next, print the logical name of the binding (that's known by // ProgramInfo). - cout << "#### " << programDoc.programName << endl; + cout << "#### " << doc.programName << endl; cout << endl; for (size_t i = 0; i < languages.size(); ++i) @@ -78,7 +78,7 @@ void PrintDocs(const std::string& bindingName, } cout << endl; - cout << programDoc.shortDocumentation << " "; + cout << doc.shortDescription << " "; for (size_t i = 0; i < languages.size(); ++i) { cout << "[Detailed documentation](#" << languages[i] << "_" @@ -213,37 +213,44 @@ void PrintDocs(const std::string& bindingName, cout << "{: #" << languages[i] << "_" << bindingName << "_detailed-documentation }" << endl; cout << endl; - string doc = boost::replace_all_copy(programDoc.documentation(), - "|", "\\|"); - cout << doc << endl; - cout << endl; + string desc = boost::replace_all_copy(doc.longDescription(), + "|", "\\|"); + cout << desc << endl << endl; + if (doc.example.size() > 0) + cout << "### Example" << endl; + for (size_t j = 0; j < doc.example.size(); ++j) + { + string eg = boost::replace_all_copy(doc.example[j](), + "|", "\\|"); + cout << eg << endl << endl; + } cout << "### See also" << endl; cout << endl; - for (size_t j = 0; j < programDoc.seeAlso.size(); ++j) + for (size_t j = 0; j < doc.seeAlso.size(); ++j) { cout << " - " << "["; // We need special processing if the user has specified a binding name // starting with @ (i.e., '@kfn' or similar). - if (programDoc.seeAlso[j].first[0] == '@') - cout << GetBindingName(programDoc.seeAlso[j].first.substr(1)); + if (doc.seeAlso[j].first[0] == '@') + cout << GetBindingName(doc.seeAlso[j].first.substr(1)); else - cout << programDoc.seeAlso[j].first; + cout << doc.seeAlso[j].first; cout << "]("; // We need special handling of Doxygen information. - if (programDoc.seeAlso[j].second.substr(0, 8) == "@doxygen") + if (doc.seeAlso[j].second.substr(0, 8) == "@doxygen") { - cout << DOXYGEN_PREFIX << programDoc.seeAlso[j].second.substr(9); + cout << DOXYGEN_PREFIX << doc.seeAlso[j].second.substr(9); } - else if (programDoc.seeAlso[j].second[0] == '#') + else if (doc.seeAlso[j].second[0] == '#') { cout << "#" << languages[i] << "_" - << programDoc.seeAlso[j].second.substr(1); + << doc.seeAlso[j].second.substr(1); } else { - cout << programDoc.seeAlso[j].second; + cout << doc.seeAlso[j].second; } cout << ")" << endl; diff --git a/src/mlpack/bindings/markdown/program_doc_wrapper.hpp b/src/mlpack/bindings/markdown/program_doc_wrapper.hpp index 5811f54115..9cc333bdd6 100644 --- a/src/mlpack/bindings/markdown/program_doc_wrapper.hpp +++ b/src/mlpack/bindings/markdown/program_doc_wrapper.hpp @@ -2,8 +2,9 @@ * @file bindings/markdown/program_doc_wrapper.hpp * @author Ryan Curtin * - * A simple wrapper around ProgramDoc that also calls - * BindingInfo::RegisterProgramDoc() upon construction. + * A simple wrapper around programName, shortDescription, longDescription, + * example and seeAlso that also respectively register all the macros upon + * construction. * * mlpack is free software; you may redistribute it and/or modify it under the * terms of the 3-clause BSD license. You should have received a copy of the @@ -19,23 +20,73 @@ namespace mlpack { namespace bindings { namespace markdown { -class ProgramDocWrapper +class ProgramNameWrapper { public: /** - * Construct a ProgramDoc object and register it with - * BindingInfo::RegisterProgramDoc(). + * Register programName. */ - ProgramDocWrapper(const std::string& bindingName, - const std::string& programName, - const std::string& shortDocumentation, - const std::function& documentation, - const std::vector>& - seeAlso) + ProgramNameWrapper(const std::string& bindingName, + const std::string& programName) { - util::ProgramDoc pd(programName, shortDocumentation, documentation, - seeAlso); - BindingInfo::RegisterProgramDoc(bindingName, pd); + BindingInfo::GetSingleton().map[bindingName].programName = + std::move(programName); + } +}; + +class ShortDescriptionWrapper +{ + public: + /** + * Register shortDescription. + */ + ShortDescriptionWrapper(const std::string& bindingName, + const std::string& shortDescription) + { + BindingInfo::GetSingleton().map[bindingName].shortDescription = + std::move(shortDescription); + } +}; + +class LongDescriptionWrapper +{ + public: + /** + * Register longDescription. + */ + LongDescriptionWrapper(const std::string& bindingName, + const std::function& longDescription) + { + BindingInfo::GetSingleton().map[bindingName].longDescription = + std::move(longDescription); + } +}; + +class ExampleWrapper +{ + public: + /** + * Register example. + */ + ExampleWrapper(const std::string& bindingName, + const std::function& example) + { + BindingInfo::GetSingleton().map[bindingName].example.push_back( + std::move(example)); + } +}; + +class SeeAlsoWrapper +{ + public: + /** + * Register seeAlso. + */ + SeeAlsoWrapper(const std::string& bindingName, + const std::string& description, const std::string& link) + { + BindingInfo::GetSingleton().map[bindingName].seeAlso.push_back( + std::move(std::make_pair(description, link))); } }; diff --git a/src/mlpack/bindings/python/CMakeLists.txt b/src/mlpack/bindings/python/CMakeLists.txt index 71965da76d..191a5eb00d 100644 --- a/src/mlpack/bindings/python/CMakeLists.txt +++ b/src/mlpack/bindings/python/CMakeLists.txt @@ -14,32 +14,45 @@ if (NOT BUILD_PYTHON_BINDINGS) endif () # Generate Python setuptools file. -find_package(PythonInterp) -if (NOT PYTHON_EXECUTABLE) - not_found_return("Python not found; not building Python bindings.") -else () - message(STATUS "Found Python: ${PYTHON_EXECUTABLE}") -endif () - # Import find_python_module. include(${CMAKE_SOURCE_DIR}/CMake/FindPythonModule.cmake) +find_package(PythonInterp) +if (NOT PYTHON_EXECUTABLE) + set(PY_NOT_FOUND_MSG "${PY_NOT_FOUND_MSG}\n - Python") +endif() find_python_module(distutils) if (NOT PY_DISTUTILS) - not_found_return("distutils not found; not building Python bindings.") + set(PY_NOT_FOUND_MSG "${PY_NOT_FOUND_MSG}\n - distutils") endif () find_python_module(Cython 0.24) if (NOT PY_CYTHON) - not_found_return("Cython not found; not building Python bindings.") + set(PY_NOT_FOUND_MSG "${PY_NOT_FOUND_MSG}\n - Cython") endif () find_python_module(numpy) if (NOT PY_NUMPY) - not_found_return("numpy not found; not building Python bindings.") + set(PY_NOT_FOUND_MSG "${PY_NOT_FOUND_MSG}\n - numpy") endif () find_python_module(pandas 0.15.0) if (NOT PY_PANDAS) - not_found_return("pandas not found; not building Python bindings.") + set(PY_NOT_FOUND_MSG "${PY_NOT_FOUND_MSG}\n - pandas") endif () +## We need to check here if Python and other dependencies is even available, as +## it is require to build python-bindings. +if (FORCE_BUILD_PYTHON_BINDINGS) + if (NOT PYTHON_EXECUTABLE OR NOT PY_DISTUTILS OR NOT PY_CYTHON OR NOT PY_NUMPY + OR NOT PY_PANDAS) + unset(BUILD_PYTHON_BINDINGS CACHE) + message(FATAL_ERROR "\nCould not Build Python Bindings; the following modules are not available: ${PY_NOT_FOUND_MSG}") + endif() +else() + if (NOT PYTHON_EXECUTABLE OR NOT PY_DISTUTILS OR NOT PY_CYTHON OR NOT PY_NUMPY + OR NOT PY_PANDAS) + unset(BUILD_PYTHON_BINDINGS CACHE) + not_found_return("Not building Python bindings; the following modules are not available: ${PY_NOT_FOUND_MSG}") + endif() +endif() + set(BUILDING_PYTHON_BINDINGS ON PARENT_SCOPE) # Nothing in this directory will be compiled into mlpack. diff --git a/src/mlpack/bindings/python/generate_pyx.cpp.in b/src/mlpack/bindings/python/generate_pyx.cpp.in index 7eb2824969..09905be574 100644 --- a/src/mlpack/bindings/python/generate_pyx.cpp.in +++ b/src/mlpack/bindings/python/generate_pyx.cpp.in @@ -45,6 +45,5 @@ int main(int /* argc */, char** /* argv */) // programName is defined in mlpack_main.hpp. IO::RestoreSettings(programName); - PrintPYX(*IO::GetSingleton().doc, "${PROGRAM_MAIN_FILE}", - "${PROGRAM_NAME}"); + PrintPYX(IO::GetSingleton().doc, "${PROGRAM_MAIN_FILE}", "${PROGRAM_NAME}"); } diff --git a/src/mlpack/bindings/python/print_doc_functions_impl.hpp b/src/mlpack/bindings/python/print_doc_functions_impl.hpp index 9e6bebd987..4f282e2a68 100644 --- a/src/mlpack/bindings/python/print_doc_functions_impl.hpp +++ b/src/mlpack/bindings/python/print_doc_functions_impl.hpp @@ -133,8 +133,8 @@ std::string PrintInputOptions(const std::string& paramName, { // Unknown parameter! throw std::runtime_error("Unknown parameter '" + paramName + "' " + - "encountered while assembling documentation! Check PROGRAM_INFO() " + - "declaration."); + "encountered while assembling documentation! Check BINDING_LONG_DESC()" + + " and BINDING_EXAMPLE() declaration."); } // Continue recursion. @@ -172,8 +172,8 @@ std::string PrintOutputOptions(const std::string& paramName, { // Unknown parameter! throw std::runtime_error("Unknown parameter '" + paramName + "' " + - "encountered while assembling documentation! Check PROGRAM_INFO() " + - "declaration."); + "encountered while assembling documentation! Check BINDING_LONG_DESC()" + + " and BINDING_EXAMPLE() declaration."); } // Continue recursion. diff --git a/src/mlpack/bindings/python/print_pyx.cpp b/src/mlpack/bindings/python/print_pyx.cpp index 72b895697b..87a412346b 100644 --- a/src/mlpack/bindings/python/print_pyx.cpp +++ b/src/mlpack/bindings/python/print_pyx.cpp @@ -26,18 +26,17 @@ namespace python { * Given a list of parameter definition and program documentation, print a * generated .pyx file to stdout. * - * @param parameters List of parameters the program will use (from IO). - * @param programInfo Documentation for the program. + * @param doc Documentation for the program. * @param mainFilename Filename of the main program (i.e. * "/path/to/pca_main.cpp"). * @param functionName Name of the function (i.e. "pca"). */ -void PrintPYX(const ProgramDoc& programInfo, +void PrintPYX(const util::BindingDetails& doc, const string& mainFilename, const string& functionName) { // Restore parameters. - IO::RestoreSettings(programInfo.programName); + IO::RestoreSettings(doc.programName); std::map& parameters = IO::Parameters(); typedef std::map::iterator ParamIter; @@ -143,10 +142,19 @@ void PrintPYX(const ProgramDoc& programInfo, // Print the comment describing the function and its parameters. cout << " \"\"\"" << endl; - cout << " " << programInfo.programName << endl; + cout << " " << doc.programName << endl; cout << endl; - cout << " " << HyphenateString(programInfo.documentation(), 2) << endl; - cout << endl << endl; + + // Print the description. + cout << " " << HyphenateString(doc.longDescription(), 2) << endl << endl; + + // Next print the examples. + for (size_t j = 0; j < doc.example.size(); ++j) + { + cout << " " << util::HyphenateString(doc.example[j](), 2) << endl << endl; + } + + // Next, print information on the input options. cout << " Input parameters:" << endl; cout << endl; for (size_t i = 0; i < inputOptions.size(); ++i) @@ -184,7 +192,7 @@ void PrintPYX(const ProgramDoc& programInfo, cout << " DisableVerbose()" << endl; // Restore the parameters. - cout << " IO.RestoreSettings(\"" << programInfo.programName << "\")" + cout << " IO.RestoreSettings(\"" << doc.programName << "\")" << endl; // Determine whether or not we need to copy parameters. diff --git a/src/mlpack/bindings/python/print_pyx.hpp b/src/mlpack/bindings/python/print_pyx.hpp index 896840e3c8..999fd3153b 100644 --- a/src/mlpack/bindings/python/print_pyx.hpp +++ b/src/mlpack/bindings/python/print_pyx.hpp @@ -23,12 +23,12 @@ namespace python { * Given a list of parameter definition and program documentation, print a * generated .pyx file to stdout. * - * @param programInfo Documentation for the program. + * @param doc Documentation for the program. * @param mainFilename Filename of the main program (i.e. * "/path/to/pca_main.cpp"). * @param functionName Name of the function (i.e. "pca"). */ -void PrintPYX(const util::ProgramDoc& programInfo, +void PrintPYX(const util::BindingDetails& doc, const std::string& mainFilename, const std::string& functionName); diff --git a/src/mlpack/bindings/python/tests/test_python_binding_main.cpp b/src/mlpack/bindings/python/tests/test_python_binding_main.cpp index eca99cdff2..ec24202d8e 100644 --- a/src/mlpack/bindings/python/tests/test_python_binding_main.cpp +++ b/src/mlpack/bindings/python/tests/test_python_binding_main.cpp @@ -18,8 +18,15 @@ using namespace std; using namespace mlpack; using namespace mlpack::kernel; -PROGRAM_INFO("Python binding test", - "A simple program to test Python binding functionality.", +// Program Name. +BINDING_NAME("Python binding test"); + +// Short description. +BINDING_SHORT_DESC( + "A simple program to test Python binding functionality."); + +// Long description. +BINDING_LONG_DESC( "A simple program to test Python binding functionality. You can build " "mlpack with the BUILD_TESTS option set to off, and this binding will " "no longer be built."); diff --git a/src/mlpack/bindings/tests/test_option.hpp b/src/mlpack/bindings/tests/test_option.hpp index 95332019f3..206126f958 100644 --- a/src/mlpack/bindings/tests/test_option.hpp +++ b/src/mlpack/bindings/tests/test_option.hpp @@ -108,35 +108,6 @@ class TestOption } }; -/** - * A static object whose constructor registers program documentation with the - * IO class. This should not be used outside of IO itself, and you should use - * the PROGRAM_INFO() macro to declare these objects. Only one ProgramDoc - * object should ever exist. - * - * @see core/util/io.hpp, mlpack::IO - */ -class ProgramDoc -{ - public: - /** - * Construct a ProgramDoc object. When constructed, it will register itself - * with IO. - * - * @param programName Short string representing the name of the program. - * @param documentation Long string containing documentation on how to use the - * program and what it is. No newline characters are necessary; this is - * taken care of by IO later. - */ - ProgramDoc(const std::string& programName, - const std::string& documentation); - - //! The name of the program. - std::string programName; - //! Documentation for what the program does. - std::string documentation; -}; - } // namespace tests } // namespace bindings } // namespace mlpack diff --git a/src/mlpack/core/math/CMakeLists.txt b/src/mlpack/core/math/CMakeLists.txt index 6bacd597f8..64c8b1a15b 100644 --- a/src/mlpack/core/math/CMakeLists.txt +++ b/src/mlpack/core/math/CMakeLists.txt @@ -10,6 +10,8 @@ set(SOURCES log_add.hpp log_add_impl.hpp make_alias.hpp + multiply_slices_impl.hpp + multiply_slices.hpp random.hpp random.cpp random_basis.hpp diff --git a/src/mlpack/core/math/multiply_slices.hpp b/src/mlpack/core/math/multiply_slices.hpp new file mode 100644 index 0000000000..c07095c6d1 --- /dev/null +++ b/src/mlpack/core/math/multiply_slices.hpp @@ -0,0 +1,78 @@ +/** + * @file core/math/multiply_slices.hpp + * @author Mrityunjay Tripathi + * + * Function to perform matrix multiplication on cubes. + * + * mlpack is free software; you may redistribute it and/or modify it under the + * terms of the 3-clause BSD license. You should have received a copy of the + * 3-clause BSD license along with mlpack. If not, see + * http://www.opensource.org/licenses/BSD-3-Clause for more information. + */ + +#ifndef MLPACK_CORE_MATH_MULTIPLY_SLICES_HPP +#define MLPACK_CORE_MATH_MULTIPLY_SLICES_HPP + +#include + +namespace mlpack { +namespace math /** Miscellaneous math routines. */ { + +/** + * Matrix multiplication of slices of two cubes. This function expects + * both cubes to have the same number of slices. For example, a valid operation + * would be: cube A of shape (m, p, s) multiplied by cube B of shape (p, n, s) + * resulting in a cube of shape (m, n, s). + * + * @param cubeA First cube. + * @param cubeB Second cube. + * @param aTranspose Whether slices of first cube have to be transposed. + * @param bTranspose Whether slices of second cube have to be transposed. + */ +template +CubeType MultiplyCube2Cube(const CubeType& cubeA, + const CubeType& cubeB, + const bool aTranspose = false, + const bool bTranspose = false); +/** + * Matrix multiplication of a matrix and all the slices of a cube. This function + * is used when the first object is a matrix and the second object is a cube. + * For example, a valid operation would be: matrix A of shape (m, p) + * multiplied by cube B of shape (p, n, s) resulting in a cube + * of shape (m, n, s). + * + * @param matA The matrix as the first operand. + * @param cubeB The cube as the second operand. + * @param aTranspose Whether matrix has to be transposed. + * @param bTranspose Whether slices of cube have to be transposed. + */ +template +CubeType MultiplyMat2Cube(const MatType& matA, + const CubeType& cubeB, + const bool aTranspose = false, + const bool bTranspose = false); +/** + * Matrix multiplication of all slices of a cube with a matrix. This function + * is used when the first object is a cube and the second object is a matrix. + * For example, a valid operation would be: cube A of shape (m, p, s) + * multiplied by a matrix of shape (p, n) resulting in a cube + * of shape (m, n, s). + * + * @param cubeA The cube as the first operand. + * @param matB The matrix as the second operand. + * @param aTranspose Whether slices of cube have to be transposed. + * @param bTranspose Whether matrix has to be transposed. + */ +template +CubeType MultiplyCube2Mat(const CubeType& cubeA, + const MatType& matB, + const bool aTranspose = false, + const bool bTranspose = false); + +} // namespace math +} // namespace mlpack + +// Include implementation. +#include "multiply_slices_impl.hpp" + +#endif diff --git a/src/mlpack/core/math/multiply_slices_impl.hpp b/src/mlpack/core/math/multiply_slices_impl.hpp new file mode 100644 index 0000000000..56ffbb2f17 --- /dev/null +++ b/src/mlpack/core/math/multiply_slices_impl.hpp @@ -0,0 +1,199 @@ +/** + * @file core/math/multiply_slices_impl.hpp + * @author Mrityunjay Tripathi + * + * Implementation of matrix multiplication over slices. + * + * mlpack is free software; you may redistribute it and/or modify it under the + * terms of the 3-clause BSD license. You should have received a copy of the + * 3-clause BSD license along with mlpack. If not, see + * http://www.opensource.org/licenses/BSD-3-Clause for more information. + */ + +#ifndef MLPACK_CORE_MATH_MULTIPLY_SLICES_IMPL_HPP +#define MLPACK_CORE_MATH_MULTIPLY_SLICES_IMPL_HPP + +#include "multiply_slices.hpp" + +namespace mlpack { +namespace math /** Miscellaneous math routines. */ { + +template +CubeType MultiplyCube2Cube(const CubeType& cubeA, + const CubeType& cubeB, + const bool aTranspose, + const bool bTranspose) +{ + size_t rows = cubeA.n_rows, cols = cubeB.n_cols, slices = cubeA.n_slices; + + if (cubeA.n_slices != cubeB.n_slices) + Log::Fatal << "Number of slices is not same in both cubes." << std::endl; + + if (aTranspose && bTranspose) + { + if (cubeA.n_rows != cubeB.n_cols) + Log::Fatal << "Matrix multiplication invalid!" << std::endl; + rows = cubeA.n_cols; + cols = cubeB.n_rows; + } + else if (bTranspose && !aTranspose) + { + if (cubeA.n_cols != cubeB.n_cols) + Log::Fatal << "Matrix multiplication invalid!" << std::endl; + cols = cubeB.n_rows; + } + else if (aTranspose && !bTranspose) + { + if (cubeA.n_rows != cubeB.n_rows) + Log::Fatal << "Matrix multiplication invalid!" << std::endl; + rows = cubeA.n_cols; + } + else + { + if (cubeA.n_cols != cubeB.n_rows) + Log::Fatal << "Matrix multiplication invalid!" << std::endl; + } + + CubeType z(rows, cols, slices); + + if (aTranspose && bTranspose) + { + for (size_t i = 0; i < slices; ++i) + z.slice(i) = arma::trans(cubeB.slice(i) * cubeA.slice(i)); + } + else if (bTranspose && !aTranspose) + { + for (size_t i = 0; i < slices; ++i) + z.slice(i) = cubeA.slice(i) * cubeB.slice(i).t(); + } + else if (aTranspose && !bTranspose) + { + for (size_t i = 0; i < slices; ++i) + z.slice(i) = cubeA.slice(i).t() * cubeB.slice(i); + } + else + { + for (size_t i = 0; i < slices; ++i) + z.slice(i) = cubeA.slice(i) * cubeB.slice(i); + } + return z; +} + +template +CubeType MultiplyMat2Cube(const MatType& matA, + const CubeType& cubeB, + const bool aTranspose, + const bool bTranspose) +{ + size_t rows = matA.n_rows, cols = cubeB.n_cols, slices = cubeB.n_slices; + + if (aTranspose && bTranspose) + { + if (matA.n_rows != cubeB.n_cols) + Log::Fatal << "Matrix multiplication invalid!" << std::endl; + rows = matA.n_cols; + cols = cubeB.n_rows; + } + else if (bTranspose && !aTranspose) + { + if (matA.n_cols != cubeB.n_cols) + Log::Fatal << "Matrix multiplication invalid!" << std::endl; + cols = cubeB.n_rows; + } + else if (aTranspose && !bTranspose) + { + if (matA.n_rows != cubeB.n_rows) + Log::Fatal << "Matrix multiplication invalid!" << std::endl; + rows = matA.n_cols; + } + else + { + if (matA.n_cols != cubeB.n_rows) + Log::Fatal << "Matrix multiplication invalid!" << std::endl; + } + + CubeType z(rows, cols, slices); + + if (aTranspose && bTranspose) + { + for (size_t i = 0; i < slices; ++i) + z.slice(i) = arma::trans(cubeB.slice(i) * matA); + } + else if (bTranspose) + { + for (size_t i = 0; i < slices; ++i) + z.slice(i) = matA * cubeB.slice(i).t(); + } + else if (aTranspose) + { + for (size_t i = 0; i < slices; ++i) + z.slice(i) = matA.t() * cubeB.slice(i); + } + else + { + for (size_t i = 0; i < slices; ++i) + z.slice(i) = matA * cubeB.slice(i); + } + return z; +} + +template +CubeType MultiplyCube2Mat(const CubeType& cubeA, + const MatType& matB, + const bool aTranspose, + const bool bTranspose) +{ + size_t rows = cubeA.n_rows, cols = matB.n_cols, slices = cubeA.n_slices; + + if (aTranspose && bTranspose) + { + if (cubeA.n_rows != matB.n_cols) + Log::Fatal << "Matrix multiplication invalid!" << std::endl; + rows = cubeA.n_cols; + cols = matB.n_rows; + } + else if (bTranspose && !aTranspose) + { + if (cubeA.n_cols != matB.n_cols) + Log::Fatal << "Matrix multiplication invalid!" << std::endl; + cols = matB.n_rows; + } + else if (aTranspose && !bTranspose) + { + if (cubeA.n_rows != matB.n_rows) + Log::Fatal << "Matrix multiplication invalid!" << std::endl; + rows = cubeA.n_cols; + } + else + if (cubeA.n_cols != matB.n_rows) + Log::Fatal << "Matrix multiplication invalid!" << std::endl; + + CubeType z(rows, cols, slices); + + if (aTranspose && bTranspose) + { + for (size_t i = 0; i < slices; ++i) + z.slice(i) = arma::trans(matB * cubeA.slice(i)); + } + else if (bTranspose && !aTranspose) + { + for (size_t i = 0; i < slices; ++i) + z.slice(i) = cubeA.slice(i) * matB.t(); + } + else if (aTranspose && !bTranspose) + { + for (size_t i = 0; i < slices; ++i) + z.slice(i) = cubeA.slice(i).t() * matB; + } + else + { + for (size_t i = 0; i < slices; ++i) + z.slice(i) = cubeA.slice(i) * matB; + } + return z; +} + +} // namespace math +} // namespace mlpack + +#endif diff --git a/src/mlpack/core/util/CMakeLists.txt b/src/mlpack/core/util/CMakeLists.txt index 17a565ef87..19ddff3293 100644 --- a/src/mlpack/core/util/CMakeLists.txt +++ b/src/mlpack/core/util/CMakeLists.txt @@ -6,6 +6,7 @@ set(SOURCES arma_config_check.hpp backtrace.hpp backtrace.cpp + binding_details.hpp io.hpp io.cpp io_impl.hpp diff --git a/src/mlpack/core/util/binding_details.hpp b/src/mlpack/core/util/binding_details.hpp new file mode 100644 index 0000000000..34fabe6627 --- /dev/null +++ b/src/mlpack/core/util/binding_details.hpp @@ -0,0 +1,44 @@ +/** + * @file core/util/binding_details.hpp + * @author Yashwant Singh Parihar + * + * This defines the structure that holds documentation details for bindings. + * + * mlpack is free software; you may redistribute it and/or modify it under the + * terms of the 3-clause BSD license. You should have received a copy of the + * 3-clause BSD license along with mlpack. If not, see + * http://www.opensource.org/licenses/BSD-3-Clause for more information. + */ +#ifndef MLPACK_CORE_UTIL_BINDING_DETAILS_HPP +#define MLPACK_CORE_UTIL_BINDING_DETAILS_HPP + +#include +#include "program_doc.hpp" + +namespace mlpack { +namespace util { + +/** + * This structure holds all of the information about bindings documentation. + */ +struct BindingDetails +{ + //! Name of the binding. + std::string programName; + //! A short two-sentence description of the binding, what it does, and what + //! it is useful for. + std::string shortDescription; + //! Long string containing documentation on what it is. No newline characters + //! are necessary; this is taken care of by IO later. + std::function longDescription; + //! Documentation on how to use the binding. + std::vector> example; + //! A set of pairs of strings with useful "see also" information; each pair + //! is . + std::vector> seeAlso; +}; + +} // namespace util +} // namespace mlpack + +#endif diff --git a/src/mlpack/core/util/io.cpp b/src/mlpack/core/util/io.cpp index b5e5fe9de7..12df2a50c6 100644 --- a/src/mlpack/core/util/io.cpp +++ b/src/mlpack/core/util/io.cpp @@ -17,19 +17,15 @@ using namespace mlpack; using namespace mlpack::util; -// Fake ProgramDoc in case none is supplied. -static ProgramDoc emptyProgramDoc = ProgramDoc("", "", []() { return ""; }, - {}); - /* Constructors, Destructors, Copy */ /* Make the constructor private, to preclude unauthorized instances */ -IO::IO() : didParse(false), doc(&emptyProgramDoc) +IO::IO() : didParse(false) { return; } // Private copy constructor; don't want copies floating around. -IO::IO(const IO& /* other */) : didParse(false), doc(&emptyProgramDoc) +IO::IO(const IO& /* other */) : didParse(false) { return; } @@ -154,20 +150,6 @@ IO& IO::GetSingleton() return singleton; } -/** - * Registers a ProgramDoc object, which contains documentation about the - * program. - * - * @param doc Pointer to the ProgramDoc object. - */ -void IO::RegisterProgramDoc(ProgramDoc* doc) -{ - // Only register the doc if it is not the dummy object we created at the - // beginning of the file (as a default value in case this is never called). - if (doc != &emptyProgramDoc) - GetSingleton().doc = doc; -} - // Get the parameters that the IO object knows about. std::map& IO::Parameters() { @@ -180,10 +162,10 @@ std::map& IO::Aliases() return GetSingleton().aliases; } -// Get the program name as set by PROGRAM_INFO(). +// Get the program name as set by BINDING_NAME(). std::string IO::ProgramName() { - return GetSingleton().doc->programName; + return GetSingleton().doc.programName; } // Set a particular parameter as passed. diff --git a/src/mlpack/core/util/io.hpp b/src/mlpack/core/util/io.hpp index c0da36f8ae..427142c897 100644 --- a/src/mlpack/core/util/io.hpp +++ b/src/mlpack/core/util/io.hpp @@ -23,6 +23,7 @@ #include #include "timers.hpp" +#include "binding_details.hpp" #include "program_doc.hpp" #include "version.hpp" @@ -32,13 +33,6 @@ #include namespace mlpack { -namespace util { - -// Externally defined in option.hpp, this class holds information about the -// program being run. -class ProgramDoc; - -} // namespace util /** * @brief Parses the command line for parameters and holds user-specified @@ -76,7 +70,7 @@ class ProgramDoc; * merely as a flag on the command line (no '=true' is required). * * Here is an example of a few parameters being defined; this is for the KNN - * executable (methods/neighbor_search/knn_main.cpp): + * binding (methods/neighbor_search/knn_main.cpp): * * @code * PARAM_STRING_REQ("reference_file", "File containing the reference dataset.", @@ -99,14 +93,24 @@ class ProgramDoc; * @section programinfo Documenting the program itself * * In addition to allowing documentation for each individual parameter and - * module, the PROGRAM_INFO() macro provides support for documenting the program - * itself. There should only be one instance of the PROGRAM_INFO() macro. + * module, the BINDING_NAME() macro provides support for documenting the + * programName, BINDING_SHORT_DESC() macro provides support for documenting the + * shortDescription, BINDING_LONG_DESC() macro provides support for documenting + * the longDescription, the BINDING_EXAMPLE() macro provides support for + * documenting the example and the BINDING_SEE_ALSO() macro provides support for + * documenting the seeAlso. There should only be one instance of the + * BINDING_NAME(), BINDING_SHORT_DESC() and BINDING_LONG_DESC() macros and there + * can be multiple instance of BINDING_EXAMPLE() and BINDING_SEE_ALSO() macro. * Below is an example: * * @code - * PROGRAM_INFO("Maximum Variance Unfolding", "This program performs maximum " + * BINDING_NAME("Maximum Variance Unfolding"); + * BINDING_SHORT_DESC("An implementation of Maximum Variance Unfolding"); + * BINDING_LONG_DESC( "This program performs maximum " * "variance unfolding on the given dataset, writing a lower-dimensional " * "unfolded dataset to the given output file."); + * BINDING_EXAMPLE("mvu", "input", "dataset", "new_dim", 5, "output", "output"); + * BINDING_SEE_ALSO("Perceptron", "#perceptron"); * @endcode * * This description should be verbose, and explain to a non-expert user what the @@ -152,10 +156,10 @@ class ProgramDoc; * * @note * Options should only be defined in files which define `main()` (that is, main - * executables). If options are defined elsewhere, they may be spuriously - * included into other executables and confuse users. Similarly, if your - * executable has options which you did not define, it is probably because the - * option is defined somewhere else and included in your executable. + * bindings). If options are defined elsewhere, they may be spuriously + * included into other bindings and confuse users. Similarly, if your + * binding has options which you did not define, it is probably because the + * option is defined somewhere else and included in your binding. * * @bug * The __COUNTER__ variable is used in most cases to guarantee a unique global @@ -240,21 +244,12 @@ class IO */ static IO& GetSingleton(); - /** - * Registers a ProgramDoc object, which contains documentation about the - * program. If this method has been called before (that is, if two - * ProgramDocs are instantiated in the program), a fatal error will occur. - * - * @param doc Pointer to the ProgramDoc object. - */ - static void RegisterProgramDoc(util::ProgramDoc* doc); - //! Return a modifiable list of parameters that IO knows about. static std::map& Parameters(); //! Return a modifiable list of aliases that IO knows about. static std::map& Aliases(); - //! Get the program name as set by the PROGRAM_INFO() macro. + //! Get the program name as set by the BINDING_NAME() macro. static std::string ProgramName(); /** @@ -313,7 +308,7 @@ class IO bool didParse; //! Holds the name of the program for --version. This is the true program - //! name (argv[0]) not what is given in ProgramDoc. + //! name (argv[0]) not what is given in BindingDetails. std::string programName; //! Holds the timer objects. @@ -322,9 +317,8 @@ class IO //! So that Timer::Start() and Timer::Stop() can access the timer variable. friend class Timer; - //! Pointer to the ProgramDoc object. - util::ProgramDoc* doc; - + //! Holds the bindingDetails objects. + util::BindingDetails doc; private: /** * Make the constructor private, to preclude unauthorized instances. diff --git a/src/mlpack/core/util/mlpack_main.hpp b/src/mlpack/core/util/mlpack_main.hpp index 35cc9ae090..1bcf2a8915 100644 --- a/src/mlpack/core/util/mlpack_main.hpp +++ b/src/mlpack/core/util/mlpack_main.hpp @@ -152,12 +152,6 @@ using Option = mlpack::bindings::tests::TestOption; // testName symbol should be defined in each binding test file #include -#undef PROGRAM_INFO -#define PROGRAM_INFO(NAME, SHORT_DESC, DESC, ...) \ - static mlpack::util::ProgramDoc \ - io_programdoc_dummy_object = mlpack::util::ProgramDoc(NAME, SHORT_DESC, \ - []() { return DESC; }, { __VA_ARGS__ }) - #elif(BINDING_TYPE == BINDING_TYPE_PYX) // This is a Python binding. // Matrices are transposed on load/save. @@ -217,11 +211,10 @@ using Option = mlpack::bindings::python::PyOption; static const std::string testName = ""; #include -#undef PROGRAM_INFO -#define PROGRAM_INFO(NAME, SHORT_DESC, DESC, ...) \ - static mlpack::util::ProgramDoc \ - io_programdoc_dummy_object = mlpack::util::ProgramDoc(NAME, SHORT_DESC, \ - []() { return DESC; }, { __VA_ARGS__ }); \ +#undef BINDING_NAME +#define BINDING_NAME(NAME) static \ + mlpack::util::ProgramName \ + io_programname_dummy_object = mlpack::util::ProgramName(NAME); \ namespace mlpack { \ namespace bindings { \ namespace python { \ @@ -266,11 +259,10 @@ using Option = mlpack::bindings::julia::JuliaOption; static const std::string testName = ""; #include -#undef PROGRAM_INFO -#define PROGRAM_INFO(NAME, SHORT_DESC, DESC, ...) static \ - mlpack::util::ProgramDoc \ - io_programdoc_dummy_object = mlpack::util::ProgramDoc(NAME, SHORT_DESC, \ - []() { return DESC; }, { __VA_ARGS__ }); \ +#undef BINDING_NAME +#define BINDING_NAME(NAME) static \ + mlpack::util::ProgramName \ + io_programname_dummy_object = mlpack::util::ProgramName(NAME); \ namespace mlpack { \ namespace bindings { \ namespace julia { \ @@ -311,11 +303,10 @@ using Option = mlpack::bindings::go::GoOption; static const std::string testName = ""; #include -#undef PROGRAM_INFO -#define PROGRAM_INFO(NAME, SHORT_DESC, DESC, ...) \ - static mlpack::util::ProgramDoc \ - io_programdoc_dummy_object = mlpack::util::ProgramDoc(NAME, SHORT_DESC, \ - []() { return DESC; }, { __VA_ARGS__ }); \ +#undef BINDING_NAME +#define BINDING_NAME(NAME) static \ + mlpack::util::ProgramName \ + io_programname_dummy_object = mlpack::util::ProgramName(NAME); \ namespace mlpack { \ namespace bindings { \ namespace go { \ @@ -331,9 +322,11 @@ PARAM_FLAG("verbose", "Display informational messages and the full list of " #elif BINDING_TYPE == BINDING_TYPE_MARKDOWN -// We use BINDING_NAME in PROGRAM_INFO() so it needs to be defined. -#ifndef BINDING_NAME - #error "BINDING_NAME must be defined when BINDING_TYPE is Markdown!" +// We use MARKDOWN_BINDING_NAME in BINDING_NAME(), BINDING_SHORT_DESC(), +// BINDING_LONG_DESC(), BINDING_EXAMPLE() and BINDING_SEE_ALSO() +// so it needs to be defined. +#ifndef MARKDOWN_BINDING_NAME + #error "MARKDOWN_BINDING_NAME must be defined when BINDING_TYPE is Markdown!" #endif // This value doesn't actually matter, but it needs to be defined as something. @@ -396,12 +389,55 @@ using Option = mlpack::bindings::markdown::MDOption; #include #include -#undef PROGRAM_INFO -#define PROGRAM_INFO(NAME, SHORT_DESC, DESC, ...) static \ - mlpack::bindings::markdown::ProgramDocWrapper \ - io_programdoc_dummy_object = \ - mlpack::bindings::markdown::ProgramDocWrapper(BINDING_NAME, NAME, \ - SHORT_DESC, []() { return DESC; }, { __VA_ARGS__ }); \ +#undef BINDING_NAME +#undef BINDING_SHORT_DESC +#undef BINDING_LONG_DESC +#undef BINDING_EXAMPLE +#undef BINDING_SEE_ALSO + +#define BINDING_NAME(NAME) static \ + mlpack::bindings::markdown::ProgramNameWrapper \ + io_programname_dummy_object = \ + mlpack::bindings::markdown::ProgramNameWrapper( \ + MARKDOWN_BINDING_NAME, NAME); + +#define BINDING_SHORT_DESC(SHORT_DESC) static \ + mlpack::bindings::markdown::ShortDescriptionWrapper \ + io_programshort_desc_dummy_object = \ + mlpack::bindings::markdown::ShortDescriptionWrapper( \ + MARKDOWN_BINDING_NAME, SHORT_DESC); + +#define BINDING_LONG_DESC(LONG_DESC) static \ + mlpack::bindings::markdown::LongDescriptionWrapper \ + io_programlong_desc_dummy_object = \ + mlpack::bindings::markdown::LongDescriptionWrapper( \ + MARKDOWN_BINDING_NAME, []() { return std::string(LONG_DESC); }); + +#ifdef __COUNTER__ + #define BINDING_EXAMPLE(EXAMPLE) static \ + mlpack::bindings::markdown::ExampleWrapper \ + JOIN(io_programexample_dummy_object_, __COUNTER__) = \ + mlpack::bindings::markdown::ExampleWrapper(MARKDOWN_BINDING_NAME, \ + []() { return(std::string(EXAMPLE)); }); + + #define BINDING_SEE_ALSO(DESCRIPTION, LINK) static \ + mlpack::bindings::markdown::SeeAlsoWrapper \ + JOIN(io_programsee_also_dummy_object_, __COUNTER__) = \ + mlpack::bindings::markdown::SeeAlsoWrapper(MARKDOWN_BINDING_NAME, \ + DESCRIPTION, LINK); +#else + #define BINDING_EXAMPLE(EXAMPLE) static \ + mlpack::bindings::markdown::ExampleWrapper \ + JOIN(JOIN(io_programexample_dummy_object_, __LINE__), opt) = \ + mlpack::bindings::markdown::ExampleWrapper(MARKDOWN_BINDING_NAME, \ + []() { return(std::string(EXAMPLE)); }); + + #define BINDING_SEE_ALSO(DESCRIPTION, LINK) static \ + mlpack::bindings::markdown::SeeAlsoWrapper \ + JOIN(JOIN(io_programsee_also_dummy_object_, __LINE__), opt) = \ + mlpack::bindings::markdown::SeeAlsoWrapper(MARKDOWN_BINDING_NAME, \ + DESCRIPTION, LINK); +#endif PARAM_FLAG("verbose", "Display informational messages and the full list of " "parameters and timers at the end of execution.", "v"); diff --git a/src/mlpack/core/util/param.hpp b/src/mlpack/core/util/param.hpp index b346c20400..ab679a2f00 100644 --- a/src/mlpack/core/util/param.hpp +++ b/src/mlpack/core/util/param.hpp @@ -4,8 +4,8 @@ * @author Ryan Curtin * * Definition of PARAM_*_IN() and PARAM_*_OUT() macros, as well as the - * PROGRAM_INFO() macro, which are used to define input and output parameters of - * command-line programs and bindings to other languages. + * Documentation related macro, which are used to define input and output + * parameters of command-line programs and bindings to other languages. * * mlpack is free software; you may redistribute it and/or modify it under the * terms of the 3-clause BSD license. You should have received a copy of the @@ -30,6 +30,118 @@ using DatasetInfo = DatasetMapper; } // namespace mlpack /** + * @cond + * Don't document internal macros. + */ + +// These are ugly, but necessary utility functions we must use to generate a +// unique identifier inside of the PARAM() module. +#define JOIN(x, y) JOIN_AGAIN(x, y) +#define JOIN_AGAIN(x, y) x ## y + +/** @endcond */ + +/** + * Specify the program name of a binding. Only one instance of this macro + * should be present in your program! Therefore, use it in the main.cpp + * (or corresponding binding) in your program. + * + * @see mlpack::IO, PARAM_FLAG(), PARAM_INT_IN(), PARAM_DOUBLE_IN(), + * PARAM_STRING_IN(), PARAM_VECTOR_IN(), PARAM_INT_OUT(), PARAM_DOUBLE_OUT(), + * PARAM_VECTOR_OUT(), PARAM_INT_IN_REQ(), PARAM_DOUBLE_IN_REQ(), + * PARAM_STRING_IN_REQ(), PARAM_VECTOR_IN_REQ(), PARAM_INT_OUT_REQ(), + * PARAM_DOUBLE_OUT_REQ(), PARAM_VECTOR_OUT_REQ(), PARAM_STRING_OUT_REQ(). + * + * @param NAME Short string representing the name of the program. + */ +#define BINDING_NAME(NAME) static \ + mlpack::util::ProgramName \ + io_programname_dummy_object = mlpack::util::ProgramName(NAME); + +/** + * Specify the short description of a binding. Only one instance of this macro + * should be present in your program! Therefore, use it in the main.cpp + * (or corresponding binding) in your program. + * + * @see mlpack::IO, PARAM_FLAG(), PARAM_INT_IN(), PARAM_DOUBLE_IN(), + * PARAM_STRING_IN(), PARAM_VECTOR_IN(), PARAM_INT_OUT(), PARAM_DOUBLE_OUT(), + * PARAM_VECTOR_OUT(), PARAM_INT_IN_REQ(), PARAM_DOUBLE_IN_REQ(), + * PARAM_STRING_IN_REQ(), PARAM_VECTOR_IN_REQ(), PARAM_INT_OUT_REQ(), + * PARAM_DOUBLE_OUT_REQ(), PARAM_VECTOR_OUT_REQ(), PARAM_STRING_OUT_REQ(). + * + * @param SHORT_DESC Short two-sentence description of the program; it should + * describe what the program implements and does, and a quick overview of + * how it can be used and what it should be used for. + */ +#define BINDING_SHORT_DESC(SHORT_DESC) static \ + mlpack::util::ShortDescription \ + io_programshort_desc_dummy_object = mlpack::util::ShortDescription( \ + SHORT_DESC); + +/** + * Specify the long description of a binding. Only one instance of this macro + * present in your program! Therefore, use it in the main.cpp + * (or corresponding binding) in your program. + * + * @see mlpack::IO, PARAM_FLAG(), PARAM_INT_IN(), PARAM_DOUBLE_IN(), + * PARAM_STRING_IN(), PARAM_VECTOR_IN(), PARAM_INT_OUT(), PARAM_DOUBLE_OUT(), + * PARAM_VECTOR_OUT(), PARAM_INT_IN_REQ(), PARAM_DOUBLE_IN_REQ(), + * PARAM_STRING_IN_REQ(), PARAM_VECTOR_IN_REQ(), PARAM_INT_OUT_REQ(), + * PARAM_DOUBLE_OUT_REQ(), PARAM_VECTOR_OUT_REQ(), PARAM_STRING_OUT_REQ(). + * + * @param LONG_DESC Long string describing what the program does. Newlines + * should not be used here; this is taken care of by IO (however, you + * can explicitly specify newlines to denote new paragraphs). You can + * also use printing macros like PRINT_PARAM_STRING(), PRINT_DATASET(), + * and others. + */ +#define BINDING_LONG_DESC(LONG_DESC) static \ + mlpack::util::LongDescription \ + io_programlong_desc_dummy_object = mlpack::util::LongDescription( \ + []() { return std::string(LONG_DESC); }); + +/** + * Specify the example of a binding. Mutiple instance of this macro can be + * present in your program! Therefore, use it in the main.cpp + * (or corresponding binding) in your program. + * + * @see mlpack::IO, PARAM_FLAG(), PARAM_INT_IN(), PARAM_DOUBLE_IN(), + * PARAM_STRING_IN(), PARAM_VECTOR_IN(), PARAM_INT_OUT(), PARAM_DOUBLE_OUT(), + * PARAM_VECTOR_OUT(), PARAM_INT_IN_REQ(), PARAM_DOUBLE_IN_REQ(), + * PARAM_STRING_IN_REQ(), PARAM_VECTOR_IN_REQ(), PARAM_INT_OUT_REQ(), + * PARAM_DOUBLE_OUT_REQ(), PARAM_VECTOR_OUT_REQ(), PARAM_STRING_OUT_REQ(). + * + * @param EXAMPLE Long string describing a simple usage example.. Newlines + * should not be used here; this is taken care of by IO (however, you + * can explicitly specify newlines to denote new paragraphs). You can + * also use printing macros like PRINT_CALL(), PRINT_DATASET(), + * and others. + */ +#ifdef __COUNTER__ + #define BINDING_EXAMPLE(EXAMPLE) static \ + mlpack::util::Example \ + JOIN(io_programexample_dummy_object_, __COUNTER__) = \ + mlpack::util::Example( \ + []() { return(std::string(EXAMPLE)); }); +#else + #define BINDING_EXAMPLE(EXAMPLE) static \ + mlpack::util::Example \ + JOIN(JOIN(io_programexample_dummy_object_, __LINE__), opt) = \ + mlpack::util::Example( \ + []() { return(std::string(EXAMPLE)); }); +#endif + +/** + * Specify the see-also of a binding. Mutiple instance of this macro can be + * present in your program! Therefore, use it in the main.cpp + * (or corresponding binding) in your program. + * + * @see mlpack::IO, PARAM_FLAG(), PARAM_INT_IN(), PARAM_DOUBLE_IN(), + * PARAM_STRING_IN(), PARAM_VECTOR_IN(), PARAM_INT_OUT(), PARAM_DOUBLE_OUT(), + * PARAM_VECTOR_OUT(), PARAM_INT_IN_REQ(), PARAM_DOUBLE_IN_REQ(), + * PARAM_STRING_IN_REQ(), PARAM_VECTOR_IN_REQ(), PARAM_INT_OUT_REQ(), + * PARAM_DOUBLE_OUT_REQ(), PARAM_VECTOR_OUT_REQ(), PARAM_STRING_OUT_REQ(). + * * Provide a link for a binding's "see also" documentation section, which is * primarily (but not necessarily exclusively) used by the Markdown bindings * This link can be specified by calling SEE_ALSO("description", "link"), where @@ -42,36 +154,17 @@ using DatasetInfo = DatasetMapper; * - A link to a Doxygen page, using the mangled Doxygen name after a * '\@doxygen/', i.e., "@doxygen/mlpack1_1_adaboost1_1_AdaBoost". */ -#define SEE_ALSO(DESCRIPTION, LINK) {DESCRIPTION, LINK} - -/** - * Document an executable. Only one instance of this macro should be - * present in your program! Therefore, use it in the main.cpp - * (or corresponding executable) in your program. - * - * @see mlpack::IO, PARAM_FLAG(), PARAM_INT_IN(), PARAM_DOUBLE_IN(), - * PARAM_STRING_IN(), PARAM_VECTOR_IN(), PARAM_INT_OUT(), PARAM_DOUBLE_OUT(), - * PARAM_VECTOR_OUT(), PARAM_INT_IN_REQ(), PARAM_DOUBLE_IN_REQ(), - * PARAM_STRING_IN_REQ(), PARAM_VECTOR_IN_REQ(), PARAM_INT_OUT_REQ(), - * PARAM_DOUBLE_OUT_REQ(), PARAM_VECTOR_OUT_REQ(), PARAM_STRING_OUT_REQ(). - * - * @param NAME Short string representing the name of the program. - * @param SHORT_DESC Short two-sentence description of the program; it should - * describe what the program implements and does, and a quick overview of - * how it can be used and what it should be used for. - * @param DESC Long string describing what the program does and possibly a - * simple usage example. Newlines should not be used here; this is taken - * care of by IO (however, you can explicitly specify newlines to denote - * new paragraphs). You can also use printing macros like - * PRINT_PARAM_STRING(), PRINT_DATASET(), and others. - * @param ... A set of SEE_ALSO() macros that are used for generating - * documentation. See the SEE_ALSO() macro. This is a varargs argument, so - * you can add as many SEE_ALSO()s as you like. - */ -#define PROGRAM_INFO(NAME, SHORT_DESC, DESC, ...) \ - static mlpack::util::ProgramDoc \ - io_programdoc_dummy_object = mlpack::util::ProgramDoc(NAME, SHORT_DESC, \ - []() { return DESC; }, { __VA_ARGS__ } ) +#ifdef __COUNTER__ + #define BINDING_SEE_ALSO(DESCRIPTION, LINK) static \ + mlpack::util::SeeAlso \ + JOIN(io_programsee_also_dummy_object_, __COUNTER__) = \ + mlpack::util::SeeAlso(DESCRIPTION, LINK); +#else + #define BINDING_SEE_ALSO(DESCRIPTION, LINK) static \ + mlpack::util::SeeAlso \ + JOIN(JOIN(io_programsee_also_dummy_object_, __LINE__), opt) = \ + mlpack::util::SeeAlso(DESCRIPTION, LINK); +#endif /** * Define a flag parameter. @@ -82,7 +175,8 @@ using DatasetInfo = DatasetMapper; * here---it will cause problems. * @param ALIAS An alias for the parameter (one letter). * - * @see mlpack::IO, PROGRAM_INFO() + * @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), + * BINDING_EXAMPLE() and BINDING_SEE_ALSO(). * * @bug * The __COUNTER__ variable is used in most cases to guarantee a unique global @@ -108,7 +202,8 @@ using DatasetInfo = DatasetMapper; * @param ALIAS An alias for the parameter (one letter). * @param DEF Default value of the parameter. * - * @see mlpack::IO, PROGRAM_INFO() + * @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), + * BINDING_EXAMPLE() and BINDING_SEE_ALSO(). * * @bug // Use a forward declaration of the class. @@ -139,7 +234,8 @@ using DatasetInfo = DatasetMapper; * printing macros like PRINT_PARAM_STRING() or PRINT_DATASET() or others * here---it will cause problems. * - * @see mlpack::IO, PROGRAM_INFO() + * @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), + * BINDING_EXAMPLE() and BINDING_SEE_ALSO(). * * @bug * The __COUNTER__ variable is used in most cases to guarantee a unique global @@ -165,7 +261,8 @@ using DatasetInfo = DatasetMapper; * @param ALIAS An alias for the parameter (one letter). * @param DEF Default value of the parameter. * - * @see mlpack::IO, PROGRAM_INFO() + * @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), + * BINDING_EXAMPLE() and BINDING_SEE_ALSO(). * * @bug * The __COUNTER__ variable is used in most cases to guarantee a unique global @@ -195,7 +292,8 @@ using DatasetInfo = DatasetMapper; * printing macros like PRINT_PARAM_STRING() or PRINT_DATASET() or others * here---it will cause problems. * - * @see mlpack::IO, PROGRAM_INFO() + * @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), + * BINDING_EXAMPLE() and BINDING_SEE_ALSO(). * * @bug * The __COUNTER__ variable is used in most cases to guarantee a unique global @@ -213,7 +311,8 @@ using DatasetInfo = DatasetMapper; * * The parameter can then be specified on the command line with * --ID=value. If ALIAS is equal to DEF_MOD (which is set using the - * PROGRAM_INFO() macro), the parameter can be specified with just --ID=value. + * BINDING_LONG_DESC() macro), the parameter can be specified with just + * --ID=value. * * @param ID Name of the parameter. * @param DESC Quick description of the parameter (1-2 sentences). Don't use @@ -222,7 +321,8 @@ using DatasetInfo = DatasetMapper; * @param ALIAS An alias for the parameter (one letter). * @param DEF Default value of the parameter. * - * @see mlpack::IO, PROGRAM_INFO() + * @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), + * BINDING_EXAMPLE() and BINDING_SEE_ALSO(). * * @bug * The __COUNTER__ variable is used in most cases to guarantee a unique global @@ -253,7 +353,8 @@ using DatasetInfo = DatasetMapper; * here---it will cause problems. * @param ALIAS An alias for the parameter (one letter). * - * @see mlpack::IO, PROGRAM_INFO() + * @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), + * BINDING_EXAMPLE() and BINDING_SEE_ALSO(). * * @bug * The __COUNTER__ variable is used in most cases to guarantee a unique global @@ -827,7 +928,8 @@ using DatasetInfo = DatasetMapper; * here---it will cause problems. * @param ALIAS An alias for the parameter (one letter). * - * @see mlpack::IO, PROGRAM_INFO() + * @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), + * BINDING_EXAMPLE() and BINDING_SEE_ALSO(). * * @bug * The __COUNTER__ variable is used in most cases to guarantee a unique global @@ -860,7 +962,8 @@ using DatasetInfo = DatasetMapper; * here---it will cause problems. * @param ALIAS An alias for the parameter (one letter). * - * @see mlpack::IO, PROGRAM_INFO() + * @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), + * BINDING_EXAMPLE() and BINDING_SEE_ALSO(). * * @bug * The __COUNTER__ variable is used in most cases to guarantee a unique global @@ -899,7 +1002,8 @@ using DatasetInfo = DatasetMapper; * here---it will cause problems. * @param ALIAS One-character string representing the alias of the parameter. * - * @see mlpack::IO, PROGRAM_INFO() + * @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), + * BINDING_EXAMPLE() and BINDING_SEE_ALSO(). * * @bug * The __COUNTER__ variable is used in most cases to guarantee a unique global @@ -1011,7 +1115,8 @@ using DatasetInfo = DatasetMapper; * here---it will cause problems. * @param ALIAS An alias for the parameter (one letter). * - * @see mlpack::IO, PROGRAM_INFO() + * @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), + * BINDING_EXAMPLE() and BINDING_SEE_ALSO(). * * @bug * The __COUNTER__ variable is used in most cases to guarantee a unique global @@ -1035,7 +1140,8 @@ using DatasetInfo = DatasetMapper; * here---it will cause problems. * @param ALIAS An alias for the parameter (one letter). * - * @see mlpack::IO, PROGRAM_INFO() + * @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), + * BINDING_EXAMPLE() and BINDING_SEE_ALSO(). * * @bug * The __COUNTER__ variable is used in most cases to guarantee a unique global @@ -1059,7 +1165,8 @@ using DatasetInfo = DatasetMapper; * here---it will cause problems. * @param ALIAS An alias for the parameter (one letter). * - * @see mlpack::IO, PROGRAM_INFO() + * @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), + * BINDING_EXAMPLE() and BINDING_SEE_ALSO(). * * @bug * The __COUNTER__ variable is used in most cases to guarantee a unique global @@ -1085,7 +1192,8 @@ using DatasetInfo = DatasetMapper; * here---it will cause problems. * @param ALIAS An alias for the parameter (one letter). * - * @see mlpack::IO, PROGRAM_INFO() + * @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), + * BINDING_EXAMPLE() and BINDING_SEE_ALSO(). * * @bug * The __COUNTER__ variable is used in most cases to guarantee a unique global @@ -1098,18 +1206,6 @@ using DatasetInfo = DatasetMapper; #define PARAM_VECTOR_IN_REQ(T, ID, DESC, ALIAS) \ PARAM_IN(std::vector, ID, DESC, ALIAS, std::vector(), true); -/** - * @cond - * Don't document internal macros. - */ - -// These are ugly, but necessary utility functions we must use to generate a -// unique identifier inside of the PARAM() module. -#define JOIN(x, y) JOIN_AGAIN(x, y) -#define JOIN_AGAIN(x, y) x ## y - -/** @endcond */ - /** * Define an input parameter. Don't use this function; use the other ones above * that call it. Note that we are using the __LINE__ macro for naming these diff --git a/src/mlpack/core/util/program_doc.cpp b/src/mlpack/core/util/program_doc.cpp index 0dc52bf13d..44f3f8a42b 100644 --- a/src/mlpack/core/util/program_doc.cpp +++ b/src/mlpack/core/util/program_doc.cpp @@ -1,9 +1,10 @@ /** * @file core/util/program_doc.cpp + * @author Yashwant Singh Parihar * @author Ryan Curtin * - * Implementation of the ProgramDoc class. The class registers itself with IO - * when constructed. + * Implementation of mutiple classes that store information related to a binding. + * The classes register themselves with IO when constructed. * * mlpack is free software; you may redistribute it and/or modify it under the * terms of the 3-clause BSD license. You should have received a copy of the @@ -20,36 +21,70 @@ using namespace mlpack::util; using namespace std; /** - * Construct a ProgramDoc object. When constructed, it will register itself + * Construct a ProgramName object. When constructed, it will register itself * with IO. A fatal error will be thrown if more than one is constructed. * - * @param defaultModule Name of the default module. - * @param shortDocumentation A short two-sentence description of the program, - * what it does, and what it is useful for. - * @param documentation Long string containing documentation on how to use the - * program and what it is. No newline characters are necessary; this is - * taken care of by IO later. - * @param seeAlso A set of pairs of strings with useful "see also" - * information; each pair is . + * @param programName Name of the binding. */ -ProgramDoc::ProgramDoc( - const std::string programName, - const std::string shortDocumentation, - const std::function documentation, - const std::vector> seeAlso) : - programName(std::move(programName)), - shortDocumentation(std::move(shortDocumentation)), - documentation(std::move(documentation)), - seeAlso(std::move(seeAlso)) +ProgramName::ProgramName(const std::string& programName) { // Register this with IO. - IO::RegisterProgramDoc(this); + IO::GetSingleton().doc.programName = std::move(programName); } /** - * Construct an empty ProgramDoc object. + * Construct a ShortDescription object. When constructed, it will register + * itself with IO. A fatal error will be thrown if more than one is + * constructed. + * + * @param shortDescription A short two-sentence description of the binding, + * what it does, and what it is useful for. */ -ProgramDoc::ProgramDoc() +ShortDescription::ShortDescription(const std::string& shortDescription) { - IO::RegisterProgramDoc(this); + // Register this with IO. + IO::GetSingleton().doc.shortDescription = std::move(shortDescription); +} + +/** + * Construct a LongDescription object. When constructed, it will register itself + * with IO. A fatal error will be thrown if more than one is constructed. + * + * @param longDescription Long string containing documentation on + * what it is. No newline characters are necessary; this is + * taken care of by IO later. + */ +LongDescription::LongDescription( + const std::function& longDescription) +{ + // Register this with IO. + IO::GetSingleton().doc.longDescription = std::move(longDescription); +} + +/** + * Construct a Example object. When constructed, it will register itself + * with IO. + * + * @param example Documentation on how to use the binding. + */ +Example::Example( + const std::function& example) +{ + // Register this with IO. + IO::GetSingleton().doc.example.push_back(std::move(example)); +} + +/** + * Construct a SeeAlso object. When constructed, it will register itself + * with IO. + * + * @param description Description of SeeAlso. + * @param link Link of SeeAlso. + */ +SeeAlso::SeeAlso( + const std::string& description, const std::string& link) +{ + // Register this with IO. + IO::GetSingleton().doc.seeAlso.push_back(std::move( + make_pair(description, link))); } diff --git a/src/mlpack/core/util/program_doc.hpp b/src/mlpack/core/util/program_doc.hpp index 2e9ee6e533..0d71d93fe5 100644 --- a/src/mlpack/core/util/program_doc.hpp +++ b/src/mlpack/core/util/program_doc.hpp @@ -1,8 +1,10 @@ /** * @file core/util/program_doc.hpp + * @author Yashwant Singh Parihar * @author Matthew Amidon * - * The structure used to store a program's name and documentation. + * Implementation of mutiple classes that store information related to a binding. + * The classes register themselves with IO when constructed. * * mlpack is free software; you may redistribute it and/or modify it under the * terms of the 3-clause BSD license. You should have received a copy of the @@ -15,50 +17,69 @@ namespace mlpack { namespace util { -/** - * A static object whose constructor registers program documentation with the - * IO class. This should not be used outside of IO itself, and you should use - * the PROGRAM_INFO() macro to declare these objects. Only one ProgramDoc - * object should ever exist. - * - * @see core/util/io.hpp, mlpack::IO - */ -class ProgramDoc +class ProgramName { public: /** - * Construct a ProgramDoc object. When constructed, it will register itself - * with IO, and when the user calls --help (or whatever the option is named - * for the given binding type), the given function that returns a std::string - * will be returned. + * Construct a ProgramName object. When constructed, it will register itself + * with IO. A fatal error will be thrown if more than one is constructed. * - * @param programName Short string representing the name of the program. - * @param shortDocumentation A short two-sentence description of the program, - * what it does, and what it is useful for. - * @param documentation Long string containing documentation on how to use the - * program and what it is. No newline characters are necessary; this is - * taken care of by IO later. - * @param seeAlso A set of pairs of strings with useful "see also" - * information; each pair is . + * @param programName Name of the binding. */ - ProgramDoc(const std::string programName, - const std::string shortDocumentation, - const std::function documentation, - const std::vector> seeAlso); + ProgramName(const std::string& programName); +}; +class ShortDescription +{ + public: /** - * Construct an empty ProgramDoc object. (This is not meant to be used!) + * Construct a ShortDescription object. When constructed, it will register + * itself with IO. A fatal error will be thrown if more than one is + * constructed. + * + * @param shortDescription A short two-sentence description of the binding, + * what it does, and what it is useful for. */ - ProgramDoc(); + ShortDescription(const std::string& shortDescription); +}; - //! The name of the program. - std::string programName; - //! The short documentation for the program. - std::string shortDocumentation; - //! Documentation for what the program does. - std::function documentation; - //! Set of see also information. - std::vector> seeAlso; +class LongDescription +{ + public: + /** + * Construct a LongDescription object. When constructed, it will register itself + * with IO. A fatal error will be thrown if more than one is constructed. + * + * @param longDescription Long string containing documentation on + * what it is. No newline characters are necessary; this is + * taken care of by IO later. + */ + LongDescription(const std::function& longDescription); +}; + +class Example +{ + public: + /** + * Construct a Example object. When constructed, it will register itself + * with IO. + * + * @param example Documentation on how to use the binding. + */ + Example(const std::function& example); +}; + +class SeeAlso +{ + public: + /** + * Construct a SeeAlso object. When constructed, it will register itself + * with IO. + * + * @param description Description of SeeAlso. + * @param link Link of SeeAlso. + */ + SeeAlso(const std::string& description, const std::string& link); }; } // namespace util diff --git a/src/mlpack/methods/adaboost/adaboost_main.cpp b/src/mlpack/methods/adaboost/adaboost_main.cpp index 1f347d9ff3..4635d438f6 100644 --- a/src/mlpack/methods/adaboost/adaboost_main.cpp +++ b/src/mlpack/methods/adaboost/adaboost_main.cpp @@ -46,13 +46,18 @@ using namespace mlpack::tree; using namespace mlpack::perceptron; using namespace mlpack::util; -PROGRAM_INFO("AdaBoost", - // Short description. +// Program Name. +BINDING_NAME("AdaBoost"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of the AdaBoost.MH (Adaptive Boosting) algorithm for " "classification. This can be used to train an AdaBoost model on labeled " "data or use an existing AdaBoost model to predict the classes of new " - "points.", - // Long description. + "points."); + +// Long description. +BINDING_LONG_DESC( "This program implements the AdaBoost (or Adaptive " "Boosting) algorithm. The variant of AdaBoost implemented here is " "AdaBoost.MH. It uses a weak learner, either decision stumps or " @@ -86,8 +91,10 @@ PROGRAM_INFO("AdaBoost", "." "\n" "Use " + PRINT_PARAM_STRING("predictions") + " instead of " + - PRINT_PARAM_STRING("output") + '.' + - "\n\n" + PRINT_PARAM_STRING("output") + '.'); + +// Example. +BINDING_EXAMPLE( "For example, to run AdaBoost on an input dataset " + PRINT_DATASET("data") + " with labels " + PRINT_DATASET("labels") + "and perceptrons as the weak learner type, storing the trained model in " + @@ -102,15 +109,17 @@ PROGRAM_INFO("AdaBoost", PRINT_DATASET("predictions") + " with the following command: " "\n\n" + PRINT_CALL("adaboost", "input_model", "model", "test", "test_data", - "predictions", "predictions"), - // See also... - SEE_ALSO("AdaBoost on Wikipedia", "https://en.wikipedia.org/wiki/AdaBoost"), - SEE_ALSO("Improved boosting algorithms using confidence-rated predictions " - "(pdf)", "http://rob.schapire.net/papers/SchapireSi98.pdf"), - SEE_ALSO("Perceptron", "#perceptron"), - SEE_ALSO("Decision Stump", "#decision_stump"), - SEE_ALSO("mlpack::adaboost::AdaBoost C++ class documentation", - "@doxygen/classmlpack_1_1adaboost_1_1AdaBoost.html")); + "predictions", "predictions")); + +// See also... +BINDING_SEE_ALSO("AdaBoost on Wikipedia", "https://en.wikipedia.org/wiki/" + "AdaBoost"); +BINDING_SEE_ALSO("Improved boosting algorithms using confidence-rated " + "predictions (pdf)", "http://rob.schapire.net/papers/SchapireSi98.pdf"); +BINDING_SEE_ALSO("Perceptron", "#perceptron"); +BINDING_SEE_ALSO("Decision Stump", "#decision_stump"); +BINDING_SEE_ALSO("mlpack::adaboost::AdaBoost C++ class documentation", + "@doxygen/classmlpack_1_1adaboost_1_1AdaBoost.html"); // Input for training. PARAM_MATRIX_IN("training", "Dataset for training AdaBoost.", "t"); diff --git a/src/mlpack/methods/ann/layer/CMakeLists.txt b/src/mlpack/methods/ann/layer/CMakeLists.txt index 8f7908d912..34ea03c6a7 100644 --- a/src/mlpack/methods/ann/layer/CMakeLists.txt +++ b/src/mlpack/methods/ann/layer/CMakeLists.txt @@ -71,6 +71,8 @@ set(SOURCES mean_pooling_impl.hpp minibatch_discrimination.hpp minibatch_discrimination_impl.hpp + multihead_attention_impl.hpp + multihead_attention.hpp multiply_constant.hpp multiply_constant_impl.hpp multiply_merge.hpp @@ -79,6 +81,8 @@ set(SOURCES noisylinear_impl.hpp parametric_relu.hpp parametric_relu_impl.hpp + positional_encoding.hpp + positional_encoding_impl.hpp recurrent.hpp recurrent_impl.hpp recurrent_attention.hpp diff --git a/src/mlpack/methods/ann/layer/layer.hpp b/src/mlpack/methods/ann/layer/layer.hpp index 3983c6f63c..d005d1eb42 100644 --- a/src/mlpack/methods/ann/layer/layer.hpp +++ b/src/mlpack/methods/ann/layer/layer.hpp @@ -44,17 +44,20 @@ #include "leaky_relu.hpp" #include "linear.hpp" #include "linear_no_bias.hpp" +#include "linear3d.hpp" #include "log_softmax.hpp" #include "lookup.hpp" #include "lstm.hpp" #include "max_pooling.hpp" #include "mean_pooling.hpp" #include "minibatch_discrimination.hpp" +#include "multihead_attention.hpp" #include "multiply_constant.hpp" #include "multiply_merge.hpp" #include "noisylinear.hpp" #include "padding.hpp" #include "parametric_relu.hpp" +#include "positional_encoding.hpp" #include "recurrent_attention.hpp" #include "recurrent.hpp" #include "reinforce_normal.hpp" diff --git a/src/mlpack/methods/ann/layer/layer_types.hpp b/src/mlpack/methods/ann/layer/layer_types.hpp index 983f3baa84..1d7fd0ccba 100644 --- a/src/mlpack/methods/ann/layer/layer_types.hpp +++ b/src/mlpack/methods/ann/layer/layer_types.hpp @@ -31,8 +31,10 @@ #include #include #include +#include #include #include +#include #include #include #include @@ -40,6 +42,7 @@ #include #include #include +#include #include #include #include @@ -96,6 +99,11 @@ template class NoisyLinear; +template +class Linear3D; + template @@ -106,6 +114,11 @@ template class MiniBatchDiscrimination; +template +class MultiheadAttention; + template @@ -205,8 +218,10 @@ template *, Glimpse*, Highway*, + MultiheadAttention*, Recurrent*, RecurrentAttention*, ReinforceNormal*, @@ -218,7 +233,8 @@ using MoreTypes = boost::variant< VRClassReward*, VirtualBatchNorm*, RBF*, - BaseLayer* + BaseLayer*, + PositionalEncoding* >; template diff --git a/src/mlpack/methods/ann/layer/linear3d.hpp b/src/mlpack/methods/ann/layer/linear3d.hpp new file mode 100644 index 0000000000..9562074cf7 --- /dev/null +++ b/src/mlpack/methods/ann/layer/linear3d.hpp @@ -0,0 +1,183 @@ +/** + * @file methods/ann/layer/linear3d.hpp + * @author Mrityunjay Tripathi + * + * Definition of the Linear layer class which accepts 3D input. + * + * mlpack is free software; you may redistribute it and/or modify it under the + * terms of the 3-clause BSD license. You should have received a copy of the + * 3-clause BSD license along with mlpack. If not, see + * http://www.opensource.org/licenses/BSD-3-Clause for more information. + */ + +#ifndef MLPACK_METHODS_ANN_LAYER_LINEAR3D_HPP +#define MLPACK_METHODS_ANN_LAYER_LINEAR3D_HPP + +#include +#include +#include + +namespace mlpack { +namespace ann /** Artificial Neural Network. */ { + +/** + * Implementation of the Linear3D layer class. The Linear class represents a + * single layer of a neural network. + * + * Shape of input : (inSize * nPoints, batchSize) + * Shape of output : (outSize * nPoints, batchSize) + * + * @tparam InputDataType Type of the input data (arma::colvec, arma::mat, + * arma::sp_mat or arma::cube). + * @tparam OutputDataType Type of the output data (arma::colvec, arma::mat, + * arma::sp_mat or arma::cube). + */ +template < + typename InputDataType = arma::mat, + typename OutputDataType = arma::mat, + typename RegularizerType = NoRegularizer +> +class Linear3D +{ + public: + //! Create the Linear3D object. + Linear3D(); + + /** + * Create the Linear3D layer object using the specified number of units. + * + * @param inSize The number of input units. + * @param outSize The number of output units. + * @param regularizer The regularizer to use, optional. + */ + Linear3D(const size_t inSize, + const size_t outSize, + RegularizerType regularizer = RegularizerType()); + + /* + * Reset the layer parameter. + */ + void Reset(); + + /** + * Ordinary feed forward pass of a neural network, evaluating the function + * f(x) by propagating the activity forward through f. + * + * @param input Input data used for evaluating the specified function. + * @param output Resulting output activation. + */ + template + void Forward(const arma::Mat& input, arma::Mat& output); + + /** + * Ordinary feed backward pass of a neural network, calculating the function + * f(x) by propagating x backwards trough f. Using the results from the feed + * forward pass. + * + * @param * (input) The propagated input activation. + * @param gy The backpropagated error. + * @param g The calculated gradient. + */ + template + void Backward(const arma::Mat& /* input */, + const arma::Mat& gy, + arma::Mat& g); + + /* + * Calculate the gradient using the output delta and the input activation. + * + * @param input The input parameter used for calculating the gradient. + * @param error The calculated error. + * @param gradient The calculated gradient. + */ + template + void Gradient(const arma::Mat& input, + const arma::Mat& error, + arma::Mat& gradient); + + //! Get the parameters. + OutputDataType const& Parameters() const { return weights; } + //! Modify the parameters. + OutputDataType& Parameters() { return weights; } + + //! Get the input parameter. + InputDataType const& InputParameter() const { return inputParameter; } + //! Modify the input parameter. + InputDataType& InputParameter() { return inputParameter; } + + //! Get the output parameter. + OutputDataType const& OutputParameter() const { return outputParameter; } + //! Modify the output parameter. + OutputDataType& OutputParameter() { return outputParameter; } + + //! Get the delta. + OutputDataType const& Delta() const { return delta; } + //! Modify the delta. + OutputDataType& Delta() { return delta; } + + //! Get the input size. + size_t InputSize() const { return inSize; } + + //! Get the output size. + size_t OutputSize() const { return outSize; } + + //! Get the gradient. + OutputDataType const& Gradient() const { return gradient; } + //! Modify the gradient. + OutputDataType& Gradient() { return gradient; } + + //! Get the weight of the layer. + OutputDataType const& Weight() const { return weight; } + //! Modify the weight of the layer. + OutputDataType& Weight() { return weight; } + + //! Get the bias of the layer. + OutputDataType const& Bias() const { return bias; } + //! Modify the bias weights of the layer. + OutputDataType& Bias() { return bias; } + + /** + * Serialize the layer + */ + template + void serialize(Archive& ar, const unsigned int /* version */); + + private: + //! Locally-stored number of input units. + size_t inSize; + + //! Locally-stored number of output units. + size_t outSize; + + //! Locally-stored weight object. + OutputDataType weights; + + //! Locally-stored weight parameters. + OutputDataType weight; + + //! Locally-stored bias term parameters. + OutputDataType bias; + + //! Locally-stored delta object. + OutputDataType delta; + + //! Locally-stored gradient object. + OutputDataType gradient; + + //! Locally-stored input parameter object. + InputDataType inputParameter; + + //! Locally-stored output parameter object. + OutputDataType outputParameter; + + //! Locally-stored regularizer object. + RegularizerType regularizer; +}; // class Linear + +} // namespace ann +} // namespace mlpack + +// Include implementation. +#include "linear3d_impl.hpp" + +#endif diff --git a/src/mlpack/methods/ann/layer/linear3d_impl.hpp b/src/mlpack/methods/ann/layer/linear3d_impl.hpp new file mode 100644 index 0000000000..97df023e37 --- /dev/null +++ b/src/mlpack/methods/ann/layer/linear3d_impl.hpp @@ -0,0 +1,178 @@ +/** + * @file methods/ann/layer/linear3d_impl.hpp + * @author Mrityunjay Tripathi + * + * Implementation of the Linear layer class which accepts 3D input. + * + * mlpack is free software; you may redistribute it and/or modify it under the + * terms of the 3-clause BSD license. You should have received a copy of the + * 3-clause BSD license along with mlpack. If not, see + * http://www.opensource.org/licenses/BSD-3-Clause for more information. + */ +#ifndef MLPACK_METHODS_ANN_LAYER_LINEAR3D_IMPL_HPP +#define MLPACK_METHODS_ANN_LAYER_LINEAR3D_IMPL_HPP + +// In case it hasn't yet been included. +#include "linear3d.hpp" + +namespace mlpack { +namespace ann /** Artificial Neural Network. */ { + +template +Linear3D::Linear3D() : + inSize(0), + outSize(0) +{ + // Nothing to do here. +} + +template +Linear3D::Linear3D( + const size_t inSize, + const size_t outSize, + RegularizerType regularizer) : + inSize(inSize), + outSize(outSize), + regularizer(regularizer) +{ + weights.set_size(outSize * inSize + outSize, 1); +} + +template +void Linear3D::Reset() +{ + typedef typename arma::Mat MatType; + + weight = MatType(weights.memptr(), outSize, inSize, false, false); + bias = MatType(weights.memptr() + weight.n_elem, outSize, 1, false, false); +} + +template +template +void Linear3D::Forward( + const arma::Mat& input, arma::Mat& output) +{ + typedef typename arma::Mat MatType; + typedef typename arma::Cube CubeType; + + if (input.n_rows % inSize != 0) + { + Log::Fatal << "Number of features in the input must be divisible by inSize." + << std::endl; + } + + const size_t nPoints = input.n_rows / inSize; + const size_t batchSize = input.n_cols; + + output.set_size(outSize * nPoints, batchSize); + + const CubeType inputTemp(const_cast(input).memptr(), inSize, + nPoints, batchSize, false, false); + + for (size_t i = 0; i < batchSize; ++i) + { + // Shape of weight : (outSize, inSize). + // Shape of inputTemp : (inSize, nPoints, batchSize). + MatType z = weight * inputTemp.slice(i); + z.each_col() += bias; + output.col(i) = arma::vectorise(z); + } +} + +template +template +void Linear3D::Backward( + const arma::Mat& /* input */, + const arma::Mat& gy, + arma::Mat& g) +{ + typedef typename arma::Mat MatType; + typedef typename arma::Cube CubeType; + + if (gy.n_rows % outSize != 0) + { + Log::Fatal << "Number of rows in propagated error must be divisible by \ + outSize." << std::endl; + } + + const size_t nPoints = gy.n_rows / outSize; + const size_t batchSize = gy.n_cols; + + const CubeType gyTemp(const_cast(gy).memptr(), outSize, + nPoints, batchSize, false, false); + + g.set_size(inSize * nPoints, batchSize); + + for (size_t i = 0; i < gyTemp.n_slices; ++i) + { + // Shape of weight : (outSize, inSize). + // Shape of gyTemp : (outSize, nPoints, batchSize). + g.col(i) = arma::vectorise(weight.t() * gyTemp.slice(i)); + } +} + +template +template +void Linear3D::Gradient( + const arma::Mat& input, + const arma::Mat& error, + arma::Mat& gradient) +{ + typedef typename arma::Mat MatType; + typedef typename arma::Cube CubeType; + + if (error.n_rows % outSize != 0) + Log::Fatal << "Propagated error matrix has invalid dimension!" << std::endl; + + const size_t nPoints = input.n_rows / inSize; + const size_t batchSize = input.n_cols; + + const CubeType inputTemp(const_cast(input).memptr(), inSize, + nPoints, batchSize, false, false); + const CubeType errorTemp(const_cast(error).memptr(), outSize, + nPoints, batchSize, false, false); + + CubeType dW(outSize, inSize, batchSize); + for (size_t i = 0; i < batchSize; ++i) + { + // Shape of errorTemp : (outSize, nPoints, batchSize). + // Shape of inputTemp : (inSize, nPoints, batchSize). + dW.slice(i) = errorTemp.slice(i) * inputTemp.slice(i).t(); + } + + gradient.set_size(arma::size(weights)); + + gradient.submat(0, 0, weight.n_elem - 1, 0) + = arma::vectorise(arma::sum(dW, 2)); + + gradient.submat(weight.n_elem, 0, weights.n_elem - 1, 0) + = arma::vectorise(arma::sum(arma::sum(errorTemp, 2), 1)); + + regularizer.Evaluate(weights, gradient); +} + +template +template +void Linear3D::serialize( + Archive& ar, const unsigned int /* version */) +{ + ar & BOOST_SERIALIZATION_NVP(inSize); + ar & BOOST_SERIALIZATION_NVP(outSize); + + // This is inefficient, but we have to allocate this memory so that + // WeightSetVisitor gets the right size. + if (Archive::is_loading::value) + weights.set_size(outSize * inSize + outSize, 1); +} + +} // namespace ann +} // namespace mlpack + +#endif diff --git a/src/mlpack/methods/ann/layer/lookup.hpp b/src/mlpack/methods/ann/layer/lookup.hpp index e704a5a1f7..eb82d1b9c8 100644 --- a/src/mlpack/methods/ann/layer/lookup.hpp +++ b/src/mlpack/methods/ann/layer/lookup.hpp @@ -27,7 +27,7 @@ namespace ann /* Artificial Neural Network. */ { * the embeddings of those tokens. * * The input shape : (sequenceLength, batchSize). - * The output shape : (sequenceLength * embeddingSize, batchSize). + * The output shape : (embeddingSize, sequenceLength, batchSize). * * @tparam InputDataType Type of the input data (arma::colvec, arma::mat, * arma::sp_mat or arma::cube). diff --git a/src/mlpack/methods/ann/layer/lookup_impl.hpp b/src/mlpack/methods/ann/layer/lookup_impl.hpp index 6afcb56218..296af49574 100644 --- a/src/mlpack/methods/ann/layer/lookup_impl.hpp +++ b/src/mlpack/methods/ann/layer/lookup_impl.hpp @@ -26,7 +26,7 @@ Lookup::Lookup( vocabSize(vocabSize), embeddingSize(embeddingSize) { - weights.set_size(vocabSize, embeddingSize); + weights.set_size(embeddingSize, vocabSize); } template @@ -37,15 +37,14 @@ void Lookup::Forward( const size_t seqLength = input.n_rows; const size_t batchSize = input.n_cols; - output.set_size(seqLength * embeddingSize, batchSize); + output.set_size(embeddingSize * seqLength, batchSize); for (size_t i = 0; i < batchSize; ++i) { - //! ith column of output is a vectorized form of a matrix of shape - //! (seqLength, embeddingSize) selected as a combination of rows from the - //! weights. The MultiheadAttention class requires this particular ordering - //! of matrix dimensions. - output.col(i) = arma::vectorise(weights.rows( + // ith column of output is a vectorized form of a matrix of shape + // (embeddingSize, seqLength) selected as a combination of columns from the + // weights. + output.col(i) = arma::vectorise(weights.cols( arma::conv_to::from(input.col(i)) - 1)); } } @@ -71,14 +70,14 @@ void Lookup::Gradient( const size_t batchSize = input.n_cols; arma::Cube errorTemp(const_cast&>(error).memptr(), - seqLength, embeddingSize, batchSize, false, false); + embeddingSize, seqLength, batchSize, false, false); gradient.set_size(arma::size(weights)); gradient.zeros(); for (size_t i = 0; i < batchSize; ++i) { - gradient.rows(arma::conv_to::from(input.col(i)) - 1) + gradient.cols(arma::conv_to::from(input.col(i)) - 1) += errorTemp.slice(i); } } @@ -94,7 +93,7 @@ void Lookup::serialize( // This is inefficient, but we have to allocate this memory so that // WeightSetVisitor gets the right size. if (Archive::is_loading::value) - weights.set_size(vocabSize, embeddingSize); + weights.set_size(embeddingSize, vocabSize); } } // namespace ann diff --git a/src/mlpack/methods/ann/layer/multihead_attention.hpp b/src/mlpack/methods/ann/layer/multihead_attention.hpp new file mode 100644 index 0000000000..a4c807c7f5 --- /dev/null +++ b/src/mlpack/methods/ann/layer/multihead_attention.hpp @@ -0,0 +1,267 @@ +/** + * @file methods/ann/layer/multihead_attention.hpp + * @author Mrityunjay Tripathi + * + * Definition of the MultiheadAttention class. + * + * @code + * @article{NIPS'17, + * author = {Ashish Vaswani, Llion Jones, Noam Shazeer, Niki Parmar, + * Aidan N. Gomez, Jakob Uszkoreit, Łukasz Kaiser, + * Illia Polosukhin}, + * title = {Attention Is All You Need}, + * year = {2017}, + * url = {http://arxiv.org/abs/1706.03762v5} + * } + * @endcode + * + * mlpack is free software; you may redistribute it and/or modify it under the + * terms of the 3-clause BSD license. You should have received a copy of the + * 3-clause BSD license along with mlpack. If not, see + * http://www.opensource.org/licenses/BSD-3-Clause for more information. + */ + +#ifndef MLPACK_METHODS_ANN_LAYER_MULTIHEAD_ATTENTION_HPP +#define MLPACK_METHODS_ANN_LAYER_MULTIHEAD_ATTENTION_HPP + +#include +#include +#include +#include +#include + +namespace mlpack { +namespace ann /** Artificial Neural Network. */ { + +/** + * Multihead Attention allows the model to jointly attend to information from + * different representation subspaces at different positions. With a single + * attention head, averaging inhibits this. [arxiv.org:1706.03762v5] + * + * The MultiheadAttention class takes concatenated form of query, key and value. + * The query, key and value are concatenated into single matrix and fed to the + * Forward function as input. + * + * The query, key and value are matrices of shapes + * `(embedDim * tgtSeqLen, batchSize)`, `(embedDim * srcSeqLen, batchSize)` + * and `(embedDim * srcSeqLen, batchSize)` respectively. The output is a matrix + * of shape `(embedDim * tgtSeqLen, batchSize)`. The embeddings are stored + * consequently. + * + * @tparam InputDataType Type of the input data (arma::colvec, arma::mat, + * arma::sp_mat or arma::cube). + * @tparam OutputDataType Type of the output data (arma::colvec, arma::mat, + * arma::sp_mat or arma::cube). + * @tparam RegularizerType Type of the regularizer to be used. + */ +template < + typename InputDataType = arma::mat, + typename OutputDataType = arma::mat, + typename RegularizerType = NoRegularizer +> +class MultiheadAttention +{ + public: + /** + * Default constructor. + */ + MultiheadAttention(); + + /** + * Create the MultiheadAttention object using the specified modules. + * + * @param tgtSeqLen Target sequence length. + * @param srcSeqLen Source sequence length. + * @param embedDim Total dimension of the model. + * @param numHeads Number of parallel attention heads. + */ + MultiheadAttention(const size_t tgtSeqLen, + const size_t srcSeqLen, + const size_t embedDim, + const size_t numHeads); + + /** + * Reset the layer parameters. + */ + void Reset(); + + /** + * Ordinary feed forward pass of a neural network, evaluating the function + * f(x) by propagating the activity forward through f. + * + * @param input The query matrix. + * @param output Resulting output activation. + */ + template + void Forward(const arma::Mat& input, arma::Mat& output); + + /** + * Ordinary feed backward pass of a neural network, calculating the function + * f(x) by propagating x backwards trough f. Using the results from the feed + * forward pass. + * + * @param gy The backpropagated error. + * @param g The calculated gradient. + */ + template + void Backward(const arma::Mat& /* input */, + const arma::Mat& gy, + arma::Mat& g); + + /** + * Calculate the gradient using the output delta and the input activation. + * + * @param input The input data used for evaluating specified function. + * @param error The calculated error. + * @param gradient The calculated gradient. + */ + template + void Gradient(const arma::Mat& input, + const arma::Mat& error, + arma::Mat& gradient); + + /** + * Serialize the layer. + */ + template + void serialize(Archive& ar, const unsigned int /* version */); + + //! Get the target sequence length. + size_t TgtSeqLen() const { return tgtSeqLen; } + //! Modify the target sequence length. + size_t& TgtSeqLen() { return tgtSeqLen; } + + //! Get the source sequence length. + size_t SrcSeqLen() const { return srcSeqLen; } + //! Modify the source sequence length. + size_t& SrcSeqLen() { return srcSeqLen; } + + //! Get the embedding dimension. + size_t EmbedDim() const { return embedDim; } + //! Modify the embedding dimension. + size_t& EmbedDim() { return embedDim; } + + //! Get the number of attention heads. + size_t NumHeads() const { return numHeads; } + //! Modify the number of attention heads. + size_t& NumHeads() { return numHeads; } + + //! Get the two dimensional Attention Mask. + OutputDataType const& AttentionMask() const { return attnMask; } + //! Modify the two dimensional Attention Mask. + OutputDataType& AttentionMask() { return attnMask; } + + //! Get Key Padding Mask. + OutputDataType const& KeyPaddingMask() const { return keyPaddingMask; } + //! Modify the Key Padding Mask. + OutputDataType& KeyPaddingMask() { return keyPaddingMask; } + + //! Get the output parameter. + OutputDataType const& OutputParameter() const { return outputParameter; } + //! Modify the output parameter. + OutputDataType& OutputParameter() { return outputParameter; } + + //! Get the delta. + OutputDataType const& Delta() const { return delta; } + //! Modify the delta. + OutputDataType& Delta() { return delta; } + + //! Get the gradient. + OutputDataType const& Gradient() const { return grad; } + //! Modify the gradient. + OutputDataType& Gradient() { return grad; } + + //! Get the parameters. + OutputDataType const& Parameters() const { return weights; } + //! Modify the parameters. + OutputDataType& Parameters() { return weights; } + + private: + //! Element Type of the input. + typedef typename OutputDataType::elem_type ElemType; + + //! Target sequence length. + size_t tgtSeqLen; + + //! Source sequence lenght. + size_t srcSeqLen; + + //! Locally-stored module output size. + size_t embedDim; + + //! Locally-stored number of parallel attention heads. + size_t numHeads; + + //! Dimensionality of each head. + size_t headDim; + + //! Two dimensional Attention Mask of shape (tgtSeqLen, srcSeqLen). + OutputDataType attnMask; + + //! Key Padding Mask. + OutputDataType keyPaddingMask; + + //! Locally-stored weight matrix associated with query. + OutputDataType queryWt; + + //! Locally-stored weight matrix associated with key. + OutputDataType keyWt; + + //! Locally-stored weight matrix associated with value. + OutputDataType valueWt; + + //! Locally-stored weight matrix associated with attnWt. + OutputDataType outWt; + + //! Locally-stored bias associated with query. + OutputDataType qBias; + + //! Locally-stored bias associated with key. + OutputDataType kBias; + + //! Locall-stored bias associated with value. + OutputDataType vBias; + + //! Locally-stored bias associated with attnWt. + OutputDataType outBias; + + //! Locally-stored weights parameter. + OutputDataType weights; + + //! Locally-stored projected query matrix over linear layer. + arma::Cube qProj; + + //! Locally-stored projected key matrix over linear layer. + arma::Cube kProj; + + //! Locally-stored projected value matrix over linear layer. + arma::Cube vProj; + + //! Locally-stored result of output of dropout layer. + arma::Cube scores; + + //! Locally-stored attention output weight to be fed to last linear layer. + arma::Cube attnOut; + + //! Softmax layer to represent the probabilities of next sequence. + Softmax softmax; + + //! Locally-stored delta object. + OutputDataType delta; + + //! Locally-stored gradient. + OutputDataType grad; + + //! Locally-stored output parameter. + OutputDataType outputParameter; + + //! Locally-stored regularizer object. + RegularizerType regularizer; +}; // class MultiheadAttention +} // namespace ann +} // namespace mlpack + +// Include implementation. +#include "multihead_attention_impl.hpp" + +#endif diff --git a/src/mlpack/methods/ann/layer/multihead_attention_impl.hpp b/src/mlpack/methods/ann/layer/multihead_attention_impl.hpp new file mode 100644 index 0000000000..795d0102bd --- /dev/null +++ b/src/mlpack/methods/ann/layer/multihead_attention_impl.hpp @@ -0,0 +1,454 @@ +/** + * @file methods/ann/layer/multihead_attention_impl.hpp + * @author Mrityunjay Tripathi + * + * Implementation of the MultiheadAttention class. + * + * mlpack is free software; you may redistribute it and/or modify it under the + * terms of the 3-clause BSD license. You should have received a copy of the + * 3-clause BSD license along with mlpack. If not, see + * http://www.opensource.org/licenses/BSD-3-Clause for more information. + */ + +#ifndef MLPACK_METHODS_ANN_LAYER_MULTIHEAD_ATTENTION_IMPL_HPP +#define MLPACK_METHODS_ANN_LAYER_MULTIHEAD_ATTENTION_IMPL_HPP + +// In case it hasn't yet been included. +#include "multihead_attention.hpp" + +#include + +namespace mlpack { +namespace ann /** Artificial Neural Network. */ { + +template +MultiheadAttention:: +MultiheadAttention() : + tgtSeqLen(0), + srcSeqLen(0), + embedDim(0), + numHeads(0), + headDim(0) +{ + // Nothing to do here. +} + +template +MultiheadAttention:: +MultiheadAttention( + const size_t tgtSeqLen, + const size_t srcSeqLen, + const size_t embedDim, + const size_t numHeads) : + tgtSeqLen(tgtSeqLen), + srcSeqLen(srcSeqLen), + embedDim(embedDim), + numHeads(numHeads) +{ + if (embedDim % numHeads != 0) + { + Log::Fatal << "Embedding dimension must be divisible by number of \ + attention heads." << std::endl; + } + + headDim = embedDim / numHeads; + weights.set_size(4 * (embedDim + 1) * embedDim, 1); +} + +template +void MultiheadAttention:: +Reset() +{ + typedef typename arma::Mat MatType; + + queryWt = MatType(weights.memptr(), embedDim, embedDim, false, false); + keyWt = MatType(weights.memptr() + embedDim * embedDim, + embedDim, embedDim, false, false); + valueWt = MatType(weights.memptr() + 2 * embedDim * embedDim, + embedDim, embedDim, false, false); + outWt = MatType(weights.memptr() + 3 * embedDim * embedDim, + embedDim, embedDim, false, false); + + qBias = MatType(weights.memptr() + + 4 * embedDim * embedDim, embedDim, 1, false, false); + kBias = MatType(weights.memptr() + + (4 * embedDim + 1) * embedDim, embedDim, 1, false, false); + vBias = MatType(weights.memptr() + + (4 * embedDim + 2) * embedDim, embedDim, 1, false, false); + outBias = MatType(weights.memptr() + + (4 * embedDim + 3) * embedDim, 1, embedDim, false, false); +} + +template +template +void MultiheadAttention:: +Forward(const arma::Mat& input, arma::Mat& output) +{ + typedef typename arma::Cube CubeType; + + if (input.n_rows != embedDim * (tgtSeqLen + 2 * srcSeqLen)) + { + Log::Fatal << "Incorrect input dimensions!" << std::endl; + } + + const size_t batchSize = input.n_cols; + + // shape of output : (embedDim * tgtSeqLen, batchSize). + output.set_size(embedDim * tgtSeqLen, batchSize); + + // Reshape the input, the query, and the key into a cube from a matrix. + // The shape of q : (embedDim, tgtSeqLen, batchSize). + // The shape of k : (embedDim, srcSeqLen, batchSize). + // The shape of v : (embedDim, srcSeqLen, batchSize). + const CubeType q(const_cast&>(input).memptr(), + embedDim, tgtSeqLen, batchSize, false, false); + const CubeType k(const_cast&>(input).memptr() + + embedDim * tgtSeqLen * batchSize, + embedDim, srcSeqLen, batchSize, false, false); + const CubeType v(const_cast&>(input).memptr() + + embedDim * (tgtSeqLen + srcSeqLen) * batchSize, + embedDim, srcSeqLen, batchSize, false, false); + + // qProj, kProj, and vProj are the linearly projected query, key and value + // respectively. + qProj.set_size(tgtSeqLen, embedDim, batchSize); + kProj.set_size(srcSeqLen, embedDim, batchSize); + vProj.set_size(srcSeqLen, embedDim, batchSize); + + for (size_t i = 0; i < batchSize; ++i) + { + qProj.slice(i) = arma::trans( + queryWt * q.slice(i) + arma::repmat(qBias, 1, tgtSeqLen)); + kProj.slice(i) = arma::trans( + keyWt * k.slice(i) + arma::repmat(kBias, 1, srcSeqLen)); + vProj.slice(i) = arma::trans( + valueWt * v.slice(i) + arma::repmat(vBias, 1, srcSeqLen)); + } + + // The scaling factor sqrt(headDim) is used to prevent exploding values + // after dot product i.e. when qProj is multiplied with kProj. + qProj /= std::sqrt(headDim); + + // Split the qProj, kProj and vProj into n heads. That's what Multihead + // Attention is. + qProj.reshape(tgtSeqLen, headDim, numHeads * batchSize); + kProj.reshape(srcSeqLen, headDim, numHeads * batchSize); + vProj.reshape(srcSeqLen, headDim, numHeads * batchSize); + + // Calculate the scores i.e. perform the matrix multiplication operation + // on qProj and kProj. Here score = qProj . kProj' + scores = math::MultiplyCube2Cube(qProj, kProj, false, true); + + // Apply the attention mask if provided. The attention mask is used to black- + // out future sequences and generally used in Encoder-Decoder attention. + // The attention mask has elements 0 or -infinity. + // The shape of the attention mask : (tgtSeqLen, srcSeqLen). + if (!attnMask.is_empty()) + { + if (attnMask.n_rows != tgtSeqLen || attnMask.n_cols != srcSeqLen) + Log::Fatal << "The size of the 'attn_mask' is not correct.\n"; + scores.each_slice() += attnMask; + } + + // Apply the key padding mask when provided. It blacks-out any particular + // word in the sequence. + // The key padding mask has elements 0 or -infinity. + // The shape of keyPaddingMask : (1, srcSeqLen). + if (!keyPaddingMask.is_empty()) + { + if (keyPaddingMask.n_rows != 1 || keyPaddingMask.n_cols != srcSeqLen) + Log::Fatal << "The size of the 'keyPaddingMask' is not correct.\n"; + scores.each_slice() += arma::repmat(keyPaddingMask, tgtSeqLen, 1); + } + + for (size_t i = 0; i < numHeads * batchSize; ++i) + { + softmax.Forward(scores.slice(i), softmax.OutputParameter()); + scores.slice(i) = softmax.OutputParameter(); + } + + // Calculate the attention output i.e. matrix multiplication of softmax + // output and vProj. + // The shape of attnOutput : (tgtSeqLen, headDim, numHeads * batchSize). + attnOut = math::MultiplyCube2Cube(scores, vProj, false, false); + + // Now we will concatenate output of all the heads i.e. we will reshape + // attnOut to (tgtSeqLen, embedDim, batchSize). + attnOut.reshape(tgtSeqLen, embedDim, batchSize); + + // The final output is the linear projection of attention output. + for (size_t i = 0; i < batchSize; ++i) + { + output.col(i) = arma::vectorise(arma::trans(attnOut.slice(i) * outWt + + arma::repmat(outBias, tgtSeqLen, 1))); + } +} + +template +template +void MultiheadAttention:: +Backward(const arma::Mat& /* input */, + const arma::Mat& gy, + arma::Mat& g) +{ + typedef typename arma::Cube CubeType; + + if (gy.n_rows != tgtSeqLen * embedDim) + { + Log::Fatal << "Backpropagated error has incorrect dimensions!" << std::endl; + } + + const size_t batchSize = gy.n_cols; + g.set_size(embedDim * (tgtSeqLen + 2 * srcSeqLen), batchSize); + + // Reshape the propagated gradient into a cube. + // The shape of gyTemp : (tgtSeqLen, embedDim, batchSize). + // We need not split it into n heads now because this is the part when + // output were concatenated from n heads. + CubeType gyTemp(const_cast&>(gy).memptr(), embedDim, + tgtSeqLen, batchSize, true, false); + + // The shape of gyTemp : (embedDim, tgtSeqLen, batchSize). + // The shape of outWt : (embedDim, embedDim). + // The shape of the result : (tgtSeqLen, embedDim, batchSize). + gyTemp = math::MultiplyCube2Mat(gyTemp, outWt, true, true); + + // Now since the shape of gyTemp is (tgtSeqLen, embedDim, batchSize). We will + // split it into n heads. + // The shape of gyTemp : (tgtSeqLen, headDim, numHeads * batchSize). + gyTemp.reshape(tgtSeqLen, headDim, numHeads * batchSize); + + // Obtain backpropagted error of value. + // Shape of gyTemp : (tgtSeqLen, headDim, numHeads * batchSize). + // Shape of scores : (tgtSeqLen, srcSeqLen, numHeads * batchSize). + // The shape of tmp : (srcSeqLen, headDim, numHeads * batchSize). + CubeType tmp = math::MultiplyCube2Cube(scores, gyTemp, true, false); + + // Concatenate results of all the attention heads. + tmp.reshape(srcSeqLen, embedDim, batchSize); + + for (size_t i = 0; i < batchSize; ++i) + { + g.submat((tgtSeqLen + srcSeqLen) * embedDim, i, g.n_rows - 1, i) + = arma::vectorise(arma::trans(tmp.slice(i) * valueWt)); + } + + // The shape of gyTemp : (tgtSeqLen, headDim, numHeads * batchSize). + // The shape of vProj : (srcSeqLen, headDim, numHeads * batchSize). + // So the new shape of gyTemp : (tgtSeqLen, srcSeqLen, numHeads * batchSize). + gyTemp = math::MultiplyCube2Cube(gyTemp, vProj, false, true); + + for (size_t i = 0; i < numHeads * batchSize; ++i) + { + // We will perform backpropagation of softmax over each slice of gyTemp. + softmax.Backward(scores.slice(i), gyTemp.slice(i), gyTemp.slice(i)); + } + + // Obtain backpropagated error of key. + // The shape of qProj : (tgtSeqLen, headDim, numHeads * batchSize). + // The shape of gyTemp : (tgtSeqLen, srcSeqLen, numHeads * batchSize). + // The new shape of tmp : (srcSeqLen, headDim, numHeads * batchSize). + tmp = math::MultiplyCube2Cube(gyTemp, qProj, true, false); + + // Concatenate results of all the attention heads. + tmp.reshape(srcSeqLen, embedDim, batchSize); + + for (size_t i = 0; i < batchSize; ++i) + { + g.submat(tgtSeqLen * embedDim, i, (tgtSeqLen + srcSeqLen) * embedDim - 1, i) + = arma::vectorise(arma::trans(tmp.slice(i) * keyWt)); + } + + // Obtain backpropagated error of the query. + // The shape of kProj : (srcSeqLen, headDim, numHeads * batchSize). + // The shape of gyTemp : (tgtSeqLen, srcSeqLen, numHeads * batchSize). + // The new shape of tmp : (tgtSeqLen, headDim, numHeads * batchSize). + tmp = math::MultiplyCube2Cube(gyTemp, kProj) / std::sqrt(headDim); + + // Concatenate results of all the attention heads. + tmp.reshape(tgtSeqLen, embedDim, batchSize); + + for (size_t i = 0; i < batchSize; ++i) + { + g.submat(0, i, tgtSeqLen * embedDim - 1, i) + = arma::vectorise(arma::trans(tmp.slice(i) * queryWt)); + } +} + +template +template +void MultiheadAttention:: +Gradient(const arma::Mat& input, + const arma::Mat& error, + arma::Mat& gradient) +{ + typedef typename arma::Cube CubeType; + typedef typename arma::Mat MatType; + + if (input.n_rows != embedDim * (tgtSeqLen + 2 * srcSeqLen)) + { + Log::Fatal << "Incorrect input dimensions!" << std::endl; + } + + if (error.n_rows != tgtSeqLen * embedDim) + { + Log::Fatal << "Backpropagated error has incorrect dimensions." << std::endl; + } + + const size_t batchSize = input.n_cols; + const size_t wtSize = embedDim * embedDim; + + // The shape of gradient : (4 * embedDim * embedDim + 4 * embedDim, 1). + gradient.set_size(arma::size(weights)); + + const CubeType q(const_cast(input).memptr(), + embedDim, tgtSeqLen, batchSize, false, false); + const CubeType k(const_cast(input).memptr() + q.n_elem, + embedDim, srcSeqLen, batchSize, false, false); + const CubeType v(const_cast(input).memptr() + q.n_elem + k.n_elem, + embedDim, srcSeqLen, batchSize, false, false); + + // Reshape the propagated error into a cube. + // The shape of errorTemp : (embedDim, tgtSeqLen, batchSize). + CubeType errorTemp(const_cast&>(error).memptr(), embedDim, + tgtSeqLen, batchSize, true, false); + + // Gradient wrt. outBias, i.e. dL/d(outBias). + gradient.rows(4 * wtSize + 3 * embedDim, 4 * wtSize + 4 * embedDim - 1) + = arma::vectorise(arma::sum(arma::sum(errorTemp, 2), 1)); + + // The shape of attnOut : (tgtSeqLen, embedDim, batchSize). + // The shape of errorTemp : (embedDim, tgtSeqLen, batchSize). + // The shape of gyTemp : (embedDim, embedDim, batchSize). + CubeType gyTemp = math::MultiplyCube2Cube(attnOut, errorTemp, true, true); + + // Gradient wrt. outWt, i.e. dL/d(outWt). We will take sum of gyTemp along + // the slices and vectorise the output. + gradient.rows(3 * wtSize, 4 * wtSize - 1) + = arma::vectorise(arma::sum(gyTemp, 2)); + + // Partial derivative wrt. attnOut. + // The shape of outWt : (embedDim, embedDim). + // The shape of errorTemp : (embedDim, tgtSeqLen, batchSize). + // The shape of gyTemp : (tgtSeqLen, embedDim, batchSize). + gyTemp = math::MultiplyCube2Mat(errorTemp, outWt, true, true); + + // Now we will split it into n heads i.e. reshape it into a cube of shape + // (tgtSeqLen, headDim, numHeads * batchSize). + gyTemp.reshape(tgtSeqLen, headDim, numHeads * batchSize); + + // Shape of gyTemp : (tgtSeqLen, headDim, numHeads * batchSize). + // Shape of scores : (tgtSeqLen, srcSeqLen, numHeads * batchSize). + // The new shape of errorTemp : (srcSeqLen, headDim, numHeads * batchSize). + errorTemp = math::MultiplyCube2Cube(scores, gyTemp, true, false); + + // Now we will concatenate the propagated errors from all heads i.e. we + // will reshape errorTemp to (srcSeqLen, embedDim, batchSize). + errorTemp.reshape(srcSeqLen, embedDim, batchSize); + + // Gradient wrt. vBias, i.e. dL/d(vBias). We will take summation of errorTemp + // over all the batches and over all the sequences. + gradient.rows(4 * wtSize + 2 * embedDim, 4 * wtSize + 3 * embedDim - 1) + = arma::vectorise(arma::sum(arma::sum(errorTemp, 2), 0)); + + // Shape of v : (srcSeqLen, embedDim, batchSize). + // Shape of errorTemp : (srcSeqLen, embedDim, bathSize). + // The new shape of errorTemp : (embedDim, embedDim, batchSize). + errorTemp = math::MultiplyCube2Cube(errorTemp, v, true, true); + + // Gradient wrt. valueWt, i.e. dL/d(valueWt). We will take summation over all + // batches of errorTemp. + gradient.rows(2 * wtSize, 3 * wtSize - 1) + = arma::vectorise(arma::sum(errorTemp, 2)); + + // Now, the shape of gyTemp : (tgtSeqLen, headDim, numHeads * batchSize). + // The shape of vProj : (srcSeqLen, headDim, numHeads * batchSize). + // The new shape of errorTemp : (tgtSeqLen, srcSeqLen, numHeads * batchSize). + errorTemp = math::MultiplyCube2Cube(gyTemp, vProj, false, true); + + for (size_t i = 0; i < numHeads * batchSize; ++i) + { + // The shape of scores : (tgtSeqLen, srcSeqLen, numHeads * batchSize). + // The shape of errorTemp : (tgtSeqLen, srcSeqLen, numHeads * batchSize). + // The new shape of errorTemp remain same. + softmax.Backward(scores.slice(i), errorTemp.slice(i), errorTemp.slice(i)); + } + + // The shape of qProj : (tgtSeqLen, headDim, numHeads * batchSize). + // The shape of errorTemp : (tgtSeqLen, srcSeqLen, numHeads * batchSize). + // The shape of gyTemp : (srcSeqLen, headDim, numHeads * batchSize). + gyTemp = math::MultiplyCube2Cube(errorTemp, qProj, true, false); + + // We will now conctenate the propagated errors from all heads. + // The new shape of gyTemp : (srcSeqLen, embedDim, batchSize). + gyTemp.reshape(srcSeqLen, embedDim, batchSize); + + // Gradient wrt. kBias, i.e. dL/d(kBias). We will take summation over all the + // batches of gyTemp and then over all the sequences. + gradient.rows(4 * wtSize + embedDim, 4 * wtSize + 2 * embedDim - 1) + = arma::vectorise(arma::sum(arma::sum(gyTemp, 2), 0)); + + // The shape of k : (embedDim, srcSeqLen, batchSize). + // The shape of gyTemp : (srcSeqLen, embedDim, batchSize). + // The shape of dkeyWt : (embedDim, embedDim, batchSize). + gyTemp = math::MultiplyCube2Cube(gyTemp, k, true, true); + + // Gradient wrt. keyWt, i.e. dL/d(keyWt). We will take summation over all the + // batches of dkeyWt. + gradient.rows(wtSize, 2 * wtSize - 1) = arma::vectorise(arma::sum(gyTemp, 2)); + + // The shape of kProj : (srcSeqLen, headDim, numHeads * batchSize). + // The shape of errorTemp : (tgtSeqLen, srcSeqLen, numHeads * batchSize). + // The shape of gyTemp : (tgtSeqLen, headDim, numHeads * batchSize). + gyTemp = math::MultiplyCube2Cube(errorTemp, kProj, false, false); + + // Now, we will concatenate propagated error of all heads. + gyTemp.reshape(tgtSeqLen, embedDim, batchSize); + gyTemp /= std::sqrt(headDim); + + // Gradient wrt. qBias, i.e. dL/d(qBias). We will take summation over all the + // batches of gyTemp and over all the sequences. + gradient.rows(4 * wtSize, 4 * wtSize + embedDim - 1) + = arma::vectorise(arma::sum(arma::sum(gyTemp, 2), 0)); + + // The shape of gyTemp : (tgtSeqLen, embedDim, batchSize). + // The shape of q : (embedDim, tgtSeqLen, batchSize). + // The shape of gyTemp : (embedDim, embedDim, batchSize). + gyTemp = math::MultiplyCube2Cube(gyTemp, q, true, true); + + // Gradient wrt. queryWt, i.e. dL/d(queryBias). We will take summation over + // all the batches of gyTemp. + gradient.rows(0, wtSize - 1) = arma::vectorise(arma::sum(gyTemp, 2)); + + // Regularize according to the given regularization rule. + regularizer.Evaluate(weights, gradient); +} + +template +template +void MultiheadAttention:: +serialize(Archive& ar, const unsigned int /* version */) +{ + ar & BOOST_SERIALIZATION_NVP(tgtSeqLen); + ar & BOOST_SERIALIZATION_NVP(srcSeqLen); + ar & BOOST_SERIALIZATION_NVP(embedDim); + ar & BOOST_SERIALIZATION_NVP(numHeads); + ar & BOOST_SERIALIZATION_NVP(headDim); + + // This is inefficient, but we have to allocate this memory so that + // WeightSetVisitor gets the right size. + if (Archive::is_loading::value) + weights.set_size(4 * embedDim * (embedDim + 1), 1); +} + +} // namespace ann +} // namespace mlpack + +#endif diff --git a/src/mlpack/methods/ann/layer/positional_encoding.hpp b/src/mlpack/methods/ann/layer/positional_encoding.hpp new file mode 100644 index 0000000000..cbfcc2667d --- /dev/null +++ b/src/mlpack/methods/ann/layer/positional_encoding.hpp @@ -0,0 +1,133 @@ +/** + * @file methods/ann/layer/positional_encoding.hpp + * @author Mrityunjay Tripathi + * + * Definition of the Positional Encoding. + * + * mlpack is free software; you may redistribute it and/or modify it under the + * terms of the 3-clause BSD license. You should have received a copy of the + * 3-clause BSD license along with mlpack. If not, see + * http://www.opensource.org/licenses/BSD-3-Clause for more information. + */ +#ifndef MLPACK_METHODS_ANN_LAYER_POSITIONAL_ENCODING_HPP +#define MLPACK_METHODS_ANN_LAYER_POSITIONAL_ENCODING_HPP + +#include + +namespace mlpack { +namespace ann /** Artificial Neural Network. */ { + +/** + * Positional Encoding injects some information about the relative or absolute + * position of the tokens in the sequence. + * + * The input and the output have the same shape: + * `(embedDim * maxSequenceLength, batchSize)`. The embeddings are stored + * consequently. + * + * @tparam InputDataType Type of the input data (arma::colvec, arma::mat, + * arma::sp_mat or arma::cube). + * @tparam OutputDataType Type of the output data (arma::colvec, arma::mat, + * arma::sp_mat or arma::cube). + */ +template < + typename InputDataType = arma::mat, + typename OutputDataType = arma::mat +> +class PositionalEncoding +{ + public: + /** + * Create PositionalEncoding object. + */ + PositionalEncoding(); + + /** + * Create the PositionalEncoding layer object using the specified parameters. + * + * @param embedDim The length of the embedding vector. + * @param maxSequenceLength Number of tokens in each sequence. + */ + PositionalEncoding(const size_t embedDim, + const size_t maxSequenceLength); + + /** + * Ordinary feed forward pass of a neural network, evaluating the function + * f(x) by propagating the activity forward through f. + * + * @param input Input data used for evaluating the specified function. + * @param output Resulting output activation. + */ + template + void Forward(const arma::Mat& input, arma::Mat& output); + + /** + * Ordinary feed backward pass of a neural network, calculating the function + * f(x) by propagating x backwards trough f. Using the results from the feed + * forward pass. + * + * @param * (input) The propagated input activation. + * @param gy The backpropagated error. + * @param g The calculated gradient. + */ + template + void Backward(const arma::Mat& /* input */, + const arma::Mat& gy, + arma::Mat& g); + + //! Get the input parameter. + InputDataType const& InputParameter() const { return inputParameter; } + //! Modify the input parameter. + InputDataType& InputParameter() { return inputParameter; } + + //! Get the output parameter. + OutputDataType const& OutputParameter() const { return outputParameter; } + //! Modify the output parameter. + OutputDataType& OutputParameter() { return outputParameter; } + + //! Get the delta. + OutputDataType const& Delta() const { return delta; } + //! Modify the delta. + OutputDataType& Delta() { return delta; } + + //! Get the positional encoding vector. + InputDataType const& Encoding() const { return positionalEncoding; } + + /** + * Serialize the layer + */ + template + void serialize(Archive& ar, const unsigned int /* version */); + + private: + /** + * Initialize positional encodings for further use. + */ + void InitPositionalEncoding(); + + //! Locally-stored embedding dimension. + size_t embedDim; + + //! Locally-stored maximum sequence length that has to be encoded. + size_t maxSequenceLength; + + //! Locally-stored positional encodings. + InputDataType positionalEncoding; + + //! Locally-stored delta object. + OutputDataType delta; + + //! Locally-stored input parameter object. + InputDataType inputParameter; + + //! Locally-stored output parameter object. + OutputDataType outputParameter; +}; // class PositionalEncoding + +} // namespace ann +} // namespace mlpack + +// Include implementation. +#include "positional_encoding_impl.hpp" + +#endif diff --git a/src/mlpack/methods/ann/layer/positional_encoding_impl.hpp b/src/mlpack/methods/ann/layer/positional_encoding_impl.hpp new file mode 100644 index 0000000000..4e70c42448 --- /dev/null +++ b/src/mlpack/methods/ann/layer/positional_encoding_impl.hpp @@ -0,0 +1,90 @@ +/** + * @file methods/ann/layer/positional_encoding_impl.hpp + * @author Mrityunjay Tripathi + * + * Implementation of the Positional Encoding. + * + * mlpack is free software; you may redistribute it and/or modify it under the + * terms of the 3-clause BSD license. You should have received a copy of the + * 3-clause BSD license along with mlpack. If not, see + * http://www.opensource.org/licenses/BSD-3-Clause for more information. + */ + +#ifndef MLPACK_METHODS_ANN_LAYER_POSITIONAL_ENCODING_IMPL_HPP +#define MLPACK_METHODS_ANN_LAYER_POSITIONAL_ENCODING_IMPL_HPP + +// In case it hasn't yet been included. +#include "positional_encoding.hpp" + +namespace mlpack { +namespace ann /** Artificial Neural Network. */ { + +template +PositionalEncoding::PositionalEncoding() : + embedDim(0), + maxSequenceLength(0) +{ + // Nothing to do here. +} + +template +PositionalEncoding::PositionalEncoding( + const size_t embedDim, + const size_t maxSequenceLength) : + embedDim(embedDim), + maxSequenceLength(maxSequenceLength) +{ + InitPositionalEncoding(); +} + +template +void PositionalEncoding::InitPositionalEncoding() +{ + positionalEncoding.set_size(maxSequenceLength, embedDim); + const InputDataType position = arma::regspace(0, 1, maxSequenceLength - 1); + const InputDataType divTerm = arma::exp(arma::regspace(0, 2, embedDim - 1) + * (- std::log(10000.0) / embedDim)); + const InputDataType theta = position * divTerm.t(); + for (size_t i = 0; i < theta.n_cols; ++i) + { + positionalEncoding.col(2 * i) = arma::sin(theta.col(i)); + positionalEncoding.col(2 * i + 1) = arma::cos(theta.col(i)); + } + positionalEncoding = arma::vectorise(positionalEncoding.t()); +} + +template +template +void PositionalEncoding::Forward( + const arma::Mat& input, arma::Mat& output) +{ + if (input.n_rows != embedDim * maxSequenceLength) + Log::Fatal << "Incorrect input dimensions!" << std::endl; + + output = input.each_col() + positionalEncoding; +} + +template +template +void PositionalEncoding::Backward( + const arma::Mat& /* input */, const arma::Mat& gy, arma::Mat& g) +{ + g = gy; +} + +template +template +void PositionalEncoding::serialize( + Archive& ar, const unsigned int /* version */) +{ + ar & BOOST_SERIALIZATION_NVP(embedDim); + ar & BOOST_SERIALIZATION_NVP(maxSequenceLength); + + if (Archive::is_loading::value) + InitPositionalEncoding(); +} + +} // namespace ann +} // namespace mlpack + +#endif diff --git a/src/mlpack/methods/ann/rbm/rbm.hpp b/src/mlpack/methods/ann/rbm/rbm.hpp index 51faa83eaa..be8d939169 100644 --- a/src/mlpack/methods/ann/rbm/rbm.hpp +++ b/src/mlpack/methods/ann/rbm/rbm.hpp @@ -70,12 +70,12 @@ class RBM const bool persistence = false); // Reset the network. - template + template typename std::enable_if::value, void>::type Reset(); // Reset the network. - template + template typename std::enable_if::value, void>::type Reset(); @@ -116,9 +116,9 @@ class RBM * * @param input The visible neurons. */ - template + template typename std::enable_if::value, double>::type - FreeEnergy(arma::Mat&& input); + FreeEnergy(const arma::Mat& input); /** * This function calculates the free energy of the SpikeSlabRBM. @@ -130,10 +130,10 @@ class RBM * * @param input The visible layer neurons. */ - template + template typename std::enable_if::value, double>::type - FreeEnergy(arma::Mat&& input); + FreeEnergy(const arma::Mat& input); /** * Calculates the gradient of the RBM network on the provided input. @@ -141,9 +141,9 @@ class RBM * @param input The provided input data. * @param gradient Stores the gradient of the RBM network. */ - template + template typename std::enable_if::value, void>::type - Phase(DataType&& input, DataType&& gradient); + Phase(const InputType& input, DataType& gradient); /** * Calculates the gradient of the RBM network on the provided input. @@ -151,9 +151,9 @@ class RBM * @param input The provided input data. * @param gradient Stores the gradient of the RBM network. */ - template + template typename std::enable_if::value, void>::type - Phase(DataType&& input, DataType&& gradient); + Phase(const InputType& input, DataType& gradient); /** * This function samples the hidden layer given the visible layer using @@ -162,9 +162,9 @@ class RBM * @param input Visible layer input. * @param output The sampled hidden layer. */ - template + template typename std::enable_if::value, void>::type - SampleHidden(arma::Mat&& input, arma::Mat&& output); + SampleHidden(const arma::Mat& input, arma::Mat& output); /** * This function samples the slab outputs from the Normal distribution with @@ -176,9 +176,9 @@ class RBM * @param input Consists of both visible and spike variables. * @param output Sampled slab neurons. */ - template + template typename std::enable_if::value, void>::type - SampleHidden(arma::Mat&& input, arma::Mat&& output); + SampleHidden(const arma::Mat& input, arma::Mat& output); /** * This function samples the visible layer given the hidden layer using @@ -187,9 +187,9 @@ class RBM * @param input Hidden layer of the network. * @param output The sampled visible layer. */ - template + template typename std::enable_if::value, void>::type - SampleVisible(arma::Mat&& input, arma::Mat&& output); + SampleVisible(arma::Mat& input, arma::Mat& output); /** * Sample Hidden function samples the slab outputs from the Normal @@ -201,9 +201,9 @@ class RBM * @param input Hidden layer of the network. * @param output The sampled visible layer. */ - template + template typename std::enable_if::value, void>::type - SampleVisible(arma::Mat&& input, arma::Mat&& output); + SampleVisible(arma::Mat& input, arma::Mat& output); /** * The function calculates the mean for the visible layer. @@ -211,9 +211,9 @@ class RBM * @param input Hidden neurons from the hidden layer of the network. * @param output Visible neuron activations. */ - template + template typename std::enable_if::value, void>::type - VisibleMean(DataType&& input, DataType&& output); + VisibleMean(InputType& input, DataType& output); /** * The function calculates the mean of the Normal distribution of P(v|s, h). @@ -223,9 +223,9 @@ class RBM * @param input Consists of both the spike and slab variables. * @param output Mean of the of the Normal distribution. */ - template + template typename std::enable_if::value, void>::type - VisibleMean(DataType&& input, DataType&& output); + VisibleMean(InputType& input, DataType& output); /** * The function calculates the mean for the hidden layer. @@ -233,9 +233,9 @@ class RBM * @param input Visible neurons. * @param output Hidden neuron activations. */ - template + template typename std::enable_if::value, void>::type - HiddenMean(DataType&& input, DataType&& output); + HiddenMean(const InputType& input, DataType& output); /** * The function calculates the mean of the Normal distribution of P(s|v, h). @@ -247,9 +247,9 @@ class RBM * @param input Visible layer neurons. * @param output Consists of both the spike samples and slab samples. */ - template + template typename std::enable_if::value, void>::type - HiddenMean(DataType&& input, DataType&& output); + HiddenMean(const InputType& input, DataType& output); /** * The function calculates the mean of the distribution P(h|v), @@ -259,18 +259,18 @@ class RBM * @param visible The visible layer neurons. * @param spikeMean Indicates P(h|v). */ - template + template typename std::enable_if::value, void>::type - SpikeMean(DataType&& visible, DataType&& spikeMean); + SpikeMean(const InputType& visible, DataType& spikeMean); /** * The function samples the spike function using Bernoulli distribution. * @param spikeMean Indicates P(h|v). * @param spike Sampled binary spike variables. */ - template + template typename std::enable_if::value, void>::type - SampleSpike(DataType&& spikeMean, DataType&& spike); + SampleSpike(InputType& spikeMean, DataType& spike); /** * The function calculates the mean of Normal distribution of P(s|v, h), @@ -281,9 +281,9 @@ class RBM * @param spike The spike variables from hidden layer. * @param slabMean The mean of the Normal distribution of slab neurons. */ - template + template typename std::enable_if::value, void>::type - SlabMean(DataType&& visible, DataType&& spike, DataType&& slabMean); + SlabMean(const DataType& visible, DataType& spike, DataType& slabMean); /** * The function samples from the Normal distribution of P(s|v, h), @@ -295,9 +295,9 @@ class RBM * @param slabMean Mean of the Normal distribution of the slab neurons. * @param slab Sampled slab variable from the Normal distribution. */ - template + template typename std::enable_if::value, void>::type - SampleSlab(DataType&& slabMean, DataType&& slab); + SampleSlab(InputType& slabMean, DataType& slab); /** * This function does the k-step Gibbs Sampling. @@ -306,8 +306,8 @@ class RBM * @param output Used for storing the negative sample. * @param steps Number of Gibbs Sampling steps taken. */ - void Gibbs(arma::Mat&& input, - arma::Mat&& output, + void Gibbs(const arma::Mat& input, + arma::Mat& output, const size_t steps = SIZE_MAX); /** diff --git a/src/mlpack/methods/ann/rbm/rbm_impl.hpp b/src/mlpack/methods/ann/rbm/rbm_impl.hpp index 79122b12d0..76014848b0 100644 --- a/src/mlpack/methods/ann/rbm/rbm_impl.hpp +++ b/src/mlpack/methods/ann/rbm/rbm_impl.hpp @@ -58,7 +58,7 @@ template< typename DataType, typename PolicyType > -template +template typename std::enable_if::value, void>::type RBM::Reset() { @@ -108,10 +108,10 @@ template< typename DataType, typename PolicyType > -template +template typename std::enable_if::value, double>::type RBM::FreeEnergy( - arma::Mat&& input) + const arma::Mat& input) { preActivation = (weight.slice(0) * input); preActivation.each_col() += hiddenBias; @@ -124,11 +124,11 @@ template< typename DataType, typename PolicyType > -template +template typename std::enable_if::value, void>::type RBM::Phase( - DataType&& input, - DataType&& gradient) + const InputType& input, + DataType& gradient) { arma::Cube weightGrad = arma::Cube(gradient.memptr(), hiddenSize, visibleSize, 1, false, false); @@ -136,7 +136,7 @@ RBM::Phase( DataType hiddenBiasGrad = DataType(gradient.memptr() + weightGrad.n_elem, hiddenSize, 1, false, false); - HiddenMean(std::move(input), std::move(hiddenBiasGrad)); + HiddenMean(input, hiddenBiasGrad); weightGrad.slice(0) = hiddenBiasGrad * input.t(); } @@ -150,10 +150,10 @@ double RBM::Evaluate( const size_t i, const size_t batchSize) { - Gibbs(std::move(predictors.cols(i, i + batchSize - 1)), - std::move(negativeSamples)); - return std::fabs(FreeEnergy(std::move(predictors.cols(i, - i + batchSize - 1))) - FreeEnergy(std::move(negativeSamples))); + Gibbs(predictors.cols(i, i + batchSize - 1), + negativeSamples); + return std::fabs(FreeEnergy(predictors.cols(i, + i + batchSize - 1)) - FreeEnergy(negativeSamples)); } template< @@ -161,13 +161,13 @@ template< typename DataType, typename PolicyType > -template +template typename std::enable_if::value, void>::type RBM::SampleHidden( - arma::Mat&& input, - arma::Mat&& output) + const arma::Mat& input, + arma::Mat& output) { - HiddenMean(std::move(input), std::move(output)); + HiddenMean(input, output); for (size_t i = 0; i < output.n_elem; ++i) { @@ -180,13 +180,13 @@ template< typename DataType, typename PolicyType > -template +template typename std::enable_if::value, void>::type RBM::SampleVisible( - arma::Mat&& input, - arma::Mat&& output) + arma::Mat& input, + arma::Mat& output) { - VisibleMean(std::move(input), std::move(output)); + VisibleMean(input, output); for (size_t i = 0; i < output.n_elem; ++i) { @@ -199,10 +199,11 @@ template< typename DataType, typename PolicyType > -template +template typename std::enable_if::value, void>::type -RBM::VisibleMean(DataType&& input, - DataType&& output) +RBM::VisibleMean( + InputType& input, + DataType& output) { output = weight.slice(0).t() * input; output.each_col() += visibleBias; @@ -214,10 +215,11 @@ template< typename DataType, typename PolicyType > -template +template typename std::enable_if::value, void>::type -RBM::HiddenMean(DataType&& input, - DataType&& output) +RBM::HiddenMean( + const InputType& input, + DataType& output) { output = weight.slice(0) * input; output.each_col() += hiddenBias; @@ -230,27 +232,27 @@ template< typename PolicyType > void RBM::Gibbs( - arma::Mat&& input, - arma::Mat&& output, + const arma::Mat& input, + arma::Mat& output, const size_t steps) { this->steps = (steps == SIZE_MAX) ? this->numSteps : steps; if (persistence && !state.is_empty()) { - SampleHidden(std::move(state), std::move(gibbsTemporary)); - SampleVisible(std::move(gibbsTemporary), std::move(output)); + SampleHidden(state, gibbsTemporary); + SampleVisible(gibbsTemporary, output); } else { - SampleHidden(std::move(input), std::move(gibbsTemporary)); - SampleVisible(std::move(gibbsTemporary), std::move(output)); + SampleHidden(input, gibbsTemporary); + SampleVisible(gibbsTemporary, output); } for (size_t j = 1; j < this->steps; ++j) { - SampleHidden(std::move(output), std::move(gibbsTemporary)); - SampleVisible(std::move(gibbsTemporary), std::move(output)); + SampleHidden(output, gibbsTemporary); + SampleVisible(gibbsTemporary, output); } if (persistence) { @@ -272,14 +274,14 @@ void RBM::Gradient( positiveGradient.zeros(); negativeGradient.zeros(); - Phase(std::move(predictors.cols(i, i + batchSize - 1)), - std::move(positiveGradient)); + Phase(predictors.cols(i, i + batchSize - 1), + positiveGradient); for (size_t i = 0; i < negSteps; ++i) { - Gibbs(std::move(predictors.cols(i, i + batchSize - 1)), - std::move(negativeSamples)); - Phase(std::move(negativeSamples), std::move(tempNegativeGradient)); + Gibbs(predictors.cols(i, i + batchSize - 1), + negativeSamples); + Phase(negativeSamples, tempNegativeGradient); negativeGradient += tempNegativeGradient; } diff --git a/src/mlpack/methods/ann/rbm/spike_slab_rbm_impl.hpp b/src/mlpack/methods/ann/rbm/spike_slab_rbm_impl.hpp index a116e813fc..125c828310 100644 --- a/src/mlpack/methods/ann/rbm/spike_slab_rbm_impl.hpp +++ b/src/mlpack/methods/ann/rbm/spike_slab_rbm_impl.hpp @@ -25,7 +25,7 @@ template< typename DataType, typename PolicyType > -template +template typename std::enable_if::value, void>::type RBM::Reset() { @@ -65,10 +65,10 @@ template< typename DataType, typename PolicyType > -template +template typename std::enable_if::value, double>::type RBM::FreeEnergy( - arma::Mat&& input) + const arma::Mat& input) { ElemType freeEnergy = 0.5 * visiblePenalty(0) * arma::dot(input, input); @@ -90,11 +90,11 @@ template< typename DataType, typename PolicyType > -template +template typename std::enable_if::value, void>::type RBM::Phase( - DataType&& input, - DataType&& gradient) + const InputType& input, + DataType& gradient) { arma::Cube weightGrad = arma::Cube (gradient.memptr(), visibleSize, poolSize, hiddenSize, false, false); @@ -102,12 +102,9 @@ RBM::Phase( DataType spikeBiasGrad = DataType(gradient.memptr() + weightGrad.n_elem, hiddenSize, 1, false, false); - DataType visiblePenaltyGrad = DataType(gradient.memptr() + - weightGrad.n_elem + spikeBiasGrad.n_elem, 1, 1, false, false); - - SpikeMean(std::move(input), std::move(spikeMean)); - SampleSpike(std::move(spikeMean), std::move(spikeSamples)); - SlabMean(std::move(input), std::move(spikeSamples), std::move(slabMean)); + SpikeMean(input, spikeMean); + SampleSpike(spikeMean, spikeSamples); + SlabMean(input, spikeSamples, slabMean); for (size_t i = 0 ; i < hiddenSize; ++i) { @@ -116,9 +113,9 @@ RBM::Phase( } spikeBiasGrad = spikeMean; - - visiblePenaltyGrad = -0.5 * arma::dot(input, input) - / std::pow(input.n_cols, 2); + // Setting visiblePenaltyGrad. + gradient.row(weightGrad.n_elem + spikeBiasGrad.n_elem) = -0.5 * arma::dot( + input, input) / std::pow(input.n_cols, 2); } template< @@ -126,11 +123,11 @@ template< typename DataType, typename PolicyType > -template +template typename std::enable_if::value, void>::type RBM::SampleHidden( - arma::Mat&& input, - arma::Mat&& output) + const arma::Mat& input, + arma::Mat& output) { output.set_size(hiddenSize + poolSize * hiddenSize, 1); @@ -138,10 +135,10 @@ RBM::SampleHidden( DataType slab(output.memptr() + hiddenSize, poolSize, hiddenSize, false, false); - SpikeMean(std::move(input), std::move(spike)); - SampleSpike(std::move(spike), std::move(spike)); - SlabMean(std::move(input), std::move(spike), std::move(slab)); - SampleSlab(std::move(slab), std::move(slab)); + SpikeMean(input, spike); + SampleSpike(spike, spike); + SlabMean(input, spike, slab); + SampleSlab(slab, slab); } template< @@ -149,16 +146,16 @@ template< typename DataType, typename PolicyType > -template +template typename std::enable_if::value, void>::type RBM::SampleVisible( - arma::Mat&& input, - arma::Mat&& output) + arma::Mat& input, + arma::Mat& output) { const size_t numMaxTrials = 10; size_t k = 0; - VisibleMean(std::move(input), std::move(visibleMean)); + VisibleMean(input, visibleMean); output.set_size(visibleSize, 1); for (k = 0; k < numMaxTrials; ++k) @@ -187,11 +184,11 @@ template< typename DataType, typename PolicyType > -template +template typename std::enable_if::value, void>::type RBM::VisibleMean( - DataType&& input, - DataType&& output) + InputType& input, + DataType& output) { output.zeros(visibleSize, 1); @@ -212,11 +209,11 @@ template< typename DataType, typename PolicyType > -template +template typename std::enable_if::value, void>::type RBM::HiddenMean( - DataType&& input, - DataType&& output) + const InputType& input, + DataType& output) { output.set_size(hiddenSize + poolSize * hiddenSize, 1); @@ -224,9 +221,9 @@ RBM::HiddenMean( DataType slab(output.memptr() + hiddenSize, poolSize, hiddenSize, false, false); - SpikeMean(std::move(input), std::move(spike)); - SampleSpike(std::move(spike), std::move(spikeSamples)); - SlabMean(std::move(input), std::move(spikeSamples), std::move(slab)); + SpikeMean(input, spike); + SampleSpike(spike, spikeSamples); + SlabMean(input, spikeSamples, slab); } template< @@ -234,11 +231,11 @@ template< typename DataType, typename PolicyType > -template +template typename std::enable_if::value, void>::type RBM::SpikeMean( - DataType&& visible, - DataType&& spikeMean) + const InputType& visible, + DataType& spikeMean) { for (size_t i = 0; i < hiddenSize; ++i) { @@ -253,11 +250,11 @@ template< typename DataType, typename PolicyType > -template +template typename std::enable_if::value, void>::type RBM::SampleSpike( - DataType&& spikeMean, - DataType&& spike) + InputType& spikeMean, + DataType& spike) { for (size_t i = 0; i < hiddenSize; ++i) { @@ -270,12 +267,12 @@ template< typename DataType, typename PolicyType > -template +template typename std::enable_if::value, void>::type RBM::SlabMean( - DataType&& visible, - DataType&& spike, - DataType&& slabMean) + const DataType& visible, + DataType& spike, + DataType& slabMean) { for (size_t i = 0; i < hiddenSize; ++i) { @@ -289,11 +286,11 @@ template< typename DataType, typename PolicyType > -template +template typename std::enable_if::value, void>::type RBM::SampleSlab( - DataType&& slabMean, - DataType&& slab) + InputType& slabMean, + DataType& slab) { for (size_t i = 0; i < hiddenSize; ++i) { diff --git a/src/mlpack/methods/approx_kfn/approx_kfn_main.cpp b/src/mlpack/methods/approx_kfn/approx_kfn_main.cpp index 99696793f6..792a53042e 100644 --- a/src/mlpack/methods/approx_kfn/approx_kfn_main.cpp +++ b/src/mlpack/methods/approx_kfn/approx_kfn_main.cpp @@ -21,13 +21,18 @@ using namespace mlpack::neighbor; using namespace mlpack::util; using namespace std; -PROGRAM_INFO("Approximate furthest neighbor search", - // Short description. +// Program Name. +BINDING_NAME("Approximate furthest neighbor search"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of two strategies for furthest neighbor search. This " "can be used to compute the furthest neighbor of query point(s) from a set " "of points; furthest neighbor models can be saved and reused with future " - "query point(s).", - // Long description. + "query point(s)."); + +// Long description. +BINDING_LONG_DESC( "This program implements two strategies for furthest neighbor search. " "These strategies are:" "\n\n" @@ -69,8 +74,10 @@ PROGRAM_INFO("Approximate furthest neighbor search", PRINT_PARAM_STRING("neighbors") + " and " + PRINT_PARAM_STRING("distances") + " output parameters. Each row of these " "output matrices holds the k distances or neighbor indices for each query " - "point." - "\n\n" + "point."); + +// Example. +BINDING_EXAMPLE( "For example, to find the 5 approximate furthest neighbors with " + PRINT_DATASET("reference_set") + " as the reference set and " + PRINT_DATASET("query_set") + " as the query set using DrusillaSelect, " @@ -96,18 +103,20 @@ PROGRAM_INFO("Approximate furthest neighbor search", PRINT_DATASET("neighbors") + " by calling" "\n\n" + PRINT_CALL("approx_kfn", "input_model", "model", "query", "new_query_set", - "k", 3, "neighbors", "neighbors"), - SEE_ALSO("k-furthest-neighbor search", "#kfn"), - SEE_ALSO("k-nearest-neighbor search", "#knn"), - SEE_ALSO("Fast approximate furthest neighbors with data-dependent candidate" - " selection (pdf)", "http://ratml.org/pub/pdf/2016fast.pdf"), - SEE_ALSO("Approximate furthest neighbor in high dimensions (pdf)", + "k", 3, "neighbors", "neighbors")); + +// See also... +BINDING_SEE_ALSO("k-furthest-neighbor search", "#kfn"); +BINDING_SEE_ALSO("k-nearest-neighbor search", "#knn"); +BINDING_SEE_ALSO("Fast approximate furthest neighbors with data-dependent" + " candidate selection (pdf)", "http://ratml.org/pub/pdf/2016fast.pdf"); +BINDING_SEE_ALSO("Approximate furthest neighbor in high dimensions (pdf)", "https://pdfs.semanticscholar.org/a4b5/7b9cbf37201fb1d9a56c0f4eefad0466" - "9c20.pdf"), - SEE_ALSO("mlpack::neighbor::QDAFN class documentation", - "@doxygen/classmlpack_1_1neighbor_1_1QDAFN.html"), - SEE_ALSO("mlpack::neighbor::DrusillaSelect class documentation", - "@doxygen/classmlpack_1_1neighbor_1_1DrusillaSelect.html")); + "9c20.pdf"); +BINDING_SEE_ALSO("mlpack::neighbor::QDAFN class documentation", + "@doxygen/classmlpack_1_1neighbor_1_1QDAFN.html"); +BINDING_SEE_ALSO("mlpack::neighbor::DrusillaSelect class documentation", + "@doxygen/classmlpack_1_1neighbor_1_1DrusillaSelect.html"); PARAM_MATRIX_IN("reference", "Matrix containing the reference dataset.", "r"); PARAM_MATRIX_IN("query", "Matrix containing query points.", "q"); diff --git a/src/mlpack/methods/bayesian_linear_regression/bayesian_linear_regression_main.cpp b/src/mlpack/methods/bayesian_linear_regression/bayesian_linear_regression_main.cpp index 86fc946fe2..a9cf1cff75 100644 --- a/src/mlpack/methods/bayesian_linear_regression/bayesian_linear_regression_main.cpp +++ b/src/mlpack/methods/bayesian_linear_regression/bayesian_linear_regression_main.cpp @@ -21,10 +21,15 @@ using namespace mlpack; using namespace mlpack::regression; using namespace mlpack::util; -PROGRAM_INFO("BayesianLinearRegression", - // Short description. - "An implementation of the bayesian linear regression.", - // Long description. +// Program Name. +BINDING_NAME("BayesianLinearRegression"); + +// Short description. +BINDING_SHORT_DESC( + "An implementation of the bayesian linear regression."); + +// Long description. +BINDING_LONG_DESC( "An implementation of the bayesian linear regression." "\n" "This model is a probabilistic view and implementation of the linear " @@ -57,8 +62,10 @@ PROGRAM_INFO("BayesianLinearRegression", "responses to the test points can be saved with the " + PRINT_PARAM_STRING("predictions") + " output parameter. The " "corresponding standard deviation can be save by precising the " + - PRINT_PARAM_STRING("stds") + " parameter." - "\n\n" + PRINT_PARAM_STRING("stds") + " parameter."); + +// Example. +BINDING_EXAMPLE( "For example, the following command trains a model on the data " + PRINT_DATASET("data") + " and responses " + PRINT_DATASET("responses") + "with center set to true and scale set to false (so, Bayesian " @@ -84,15 +91,17 @@ PROGRAM_INFO("BayesianLinearRegression", "\n\n" + PRINT_CALL("bayesian_linear_regression", "input_model", "bayesian_linear_regression_model", "test", "test", - "predictions", "test_predictions", "stds", "stds"), - SEE_ALSO("Bayesian Interpolation", - "https://authors.library.caltech.edu/13792/1/MACnc92a.pdf"), - SEE_ALSO("Bayesian Linear Regression, Section 3.3", + "predictions", "test_predictions", "stds", "stds")); + +// See also... +BINDING_SEE_ALSO("Bayesian Interpolation", + "https://authors.library.caltech.edu/13792/1/MACnc92a.pdf"); +BINDING_SEE_ALSO("Bayesian Linear Regression, Section 3.3", "MLA Bishop, Christopher M. Pattern Recognition and Machine " - "Learning. New York :Springer, 2006, section 3.3."), - SEE_ALSO("mlpack::regression::BayesianLinearRegression C++ class " + "Learning. New York :Springer, 2006, section 3.3."); +BINDING_SEE_ALSO("mlpack::regression::BayesianLinearRegression C++ class " "documentation", - "@doxygen/classmlpack_1_1regression_1_1BayesianLinearRegression.html")); + "@doxygen/classmlpack_1_1regression_1_1BayesianLinearRegression.html"); PARAM_MATRIX_IN("input", "Matrix of covariates (X).", "i"); diff --git a/src/mlpack/methods/cf/cf_main.cpp b/src/mlpack/methods/cf/cf_main.cpp index 68f9bdaaba..760ddf107d 100644 --- a/src/mlpack/methods/cf/cf_main.cpp +++ b/src/mlpack/methods/cf/cf_main.cpp @@ -41,13 +41,17 @@ using namespace mlpack::svd; using namespace mlpack::util; using namespace std; -// Document program. -PROGRAM_INFO("Collaborative Filtering", - // Short description. +// Program Name. +BINDING_NAME("Collaborative Filtering"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of several collaborative filtering (CF) techniques for " "recommender systems. This can be used to train a new CF model, or use an" - " existing CF model to compute recommendations.", - // Long description. + " existing CF model to compute recommendations."); + +// Long description. +BINDING_LONG_DESC( "This program performs collaborative " "filtering (CF) on the given dataset. Given a list of user, item and " "preferences (the " + PRINT_PARAM_STRING("training") + " parameter), " @@ -111,8 +115,10 @@ PROGRAM_INFO("Collaborative Filtering", " - 'z_score' -- Z-Score Normalization\n" "\n" "A trained model may be saved to with the " + - PRINT_PARAM_STRING("output_model") + " output parameter." - "\n\n" + PRINT_PARAM_STRING("output_model") + " output parameter."); + +// Example. +BINDING_EXAMPLE( "To train a CF model on a dataset " + PRINT_DATASET("training_set") + " " "using NMF for decomposition and saving the trained model to " + PRINT_MODEL("model") + ", one could call: " @@ -126,20 +132,23 @@ PROGRAM_INFO("Collaborative Filtering", "call " "\n\n" + PRINT_CALL("cf", "input_model", "model", "query", "users", - "recommendations", 5, "output", "recommendations"), - SEE_ALSO("Collaborative filtering tutorial", "@doxygen/cftutorial.html"), - SEE_ALSO("Alternating Matrix Factorization tutorial", - "@doxygen/amftutorial.html"), - SEE_ALSO("Collaborative Filtering on Wikipedia", - "https://en.wikipedia.org/wiki/Collaborative_filtering"), - SEE_ALSO("Matrix factorization on Wikipedia", + "recommendations", 5, "output", "recommendations")); + +// See also... +BINDING_SEE_ALSO("Collaborative filtering tutorial", + "@doxygen/cftutorial.html"); +BINDING_SEE_ALSO("Alternating Matrix Factorization tutorial", + "@doxygen/amftutorial.html"); +BINDING_SEE_ALSO("Collaborative Filtering on Wikipedia", + "https://en.wikipedia.org/wiki/Collaborative_filtering"); +BINDING_SEE_ALSO("Matrix factorization on Wikipedia", "https://en.wikipedia.org/wiki/Matrix_factorization_" - "(recommender_systems)"), - SEE_ALSO("Matrix factorization techniques for recommender systems (pdf)", - "http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.441.3234" - "&rep=rep1&type=pdf"), - SEE_ALSO("mlpack::cf::CFType class documentation", - "@doxygen/classmlpack_1_1cf_1_1CFType.html")); + "(recommender_systems)"); +BINDING_SEE_ALSO("Matrix factorization techniques for recommender systems" + " (pdf)", "http://citeseerx.ist.psu.edu/viewdoc/download?doi=" + "10.1.1.441.3234&rep=rep1&type=pdf"); +BINDING_SEE_ALSO("mlpack::cf::CFType class documentation", + "@doxygen/classmlpack_1_1cf_1_1CFType.html"); // Parameters for training a model. PARAM_MATRIX_IN("training", "Input dataset to perform CF on.", "t"); diff --git a/src/mlpack/methods/dbscan/dbscan_main.cpp b/src/mlpack/methods/dbscan/dbscan_main.cpp index 1cc598a048..a9b2bcb435 100644 --- a/src/mlpack/methods/dbscan/dbscan_main.cpp +++ b/src/mlpack/methods/dbscan/dbscan_main.cpp @@ -27,11 +27,16 @@ using namespace mlpack::tree; using namespace mlpack::util; using namespace std; -PROGRAM_INFO("DBSCAN clustering", - // Short description. +// Program Name. +BINDING_NAME("DBSCAN clustering"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of DBSCAN clustering. Given a dataset, this can " - "compute and return a clustering of that dataset.", - // Long description. + "compute and return a clustering of that dataset."); + +// Long description. +BINDING_LONG_DESC( "This program implements the DBSCAN algorithm for clustering using " "accelerated tree-based range search. The type of tree that is used " "may be parameterized, or brute-force range search may also be used." @@ -58,19 +63,23 @@ PROGRAM_INFO("DBSCAN clustering", " 'hilbert-r', 'r-plus', 'r-plus-plus', 'cover', 'ball'. The " + PRINT_PARAM_STRING("single_mode") + " parameter will force single-tree " "search (as opposed to the default dual-tree search), and '" + - PRINT_PARAM_STRING("naive") + " will force brute-force range search." - "\n\n" + PRINT_PARAM_STRING("naive") + " will force brute-force range search."); + +// Example. +BINDING_EXAMPLE( "An example usage to run DBSCAN on the dataset in " + PRINT_DATASET("input") + " with a radius of 0.5 and a minimum cluster size" " of 5 is given below:" "\n\n" + - PRINT_CALL("dbscan", "input", "input", "epsilon", 0.5, "min_size", 5), - SEE_ALSO("DBSCAN on Wikipedia", "https://en.wikipedia.org/wiki/DBSCAN"), - SEE_ALSO("A density-based algorithm for discovering clusters in large " + PRINT_CALL("dbscan", "input", "input", "epsilon", 0.5, "min_size", 5)); + +// See also... +BINDING_SEE_ALSO("DBSCAN on Wikipedia", "https://en.wikipedia.org/wiki/DBSCAN"); +BINDING_SEE_ALSO("A density-based algorithm for discovering clusters in large " "spatial databases with noise (pdf)", - "http://www.aaai.org/Papers/KDD/1996/KDD96-037.pdf"), - SEE_ALSO("mlpack::dbscan::DBSCAN class documentation", - "@doxygen/classmlpack_1_1dbscan_1_1DBSCAN.html")); + "http://www.aaai.org/Papers/KDD/1996/KDD96-037.pdf"); +BINDING_SEE_ALSO("mlpack::dbscan::DBSCAN class documentation", + "@doxygen/classmlpack_1_1dbscan_1_1DBSCAN.html"); PARAM_MATRIX_IN_REQ("input", "Input dataset to cluster.", "i"); PARAM_UROW_OUT("assignments", "Output matrix for assignments of each " diff --git a/src/mlpack/methods/decision_stump/decision_stump_main.cpp b/src/mlpack/methods/decision_stump/decision_stump_main.cpp index ff7b8bde18..b928887c8e 100644 --- a/src/mlpack/methods/decision_stump/decision_stump_main.cpp +++ b/src/mlpack/methods/decision_stump/decision_stump_main.cpp @@ -21,12 +21,17 @@ using namespace mlpack::util; using namespace std; using namespace arma; -PROGRAM_INFO("Decision Stump", - // Short description. +// Program Name. +BINDING_NAME("Decision Stump"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of a decision stump, which is a single-level decision " "tree. Given labeled data, a new decision stump can be trained; or, an " - "existing decision stump can be used to classify points.", - // Long description. + "existing decision stump can be used to classify points."); + +// Long description. +BINDING_LONG_DESC( "This program implements a decision stump, which is a single-level decision" " tree. The decision stump will split on one dimension of the input data, " "and will split into multiple buckets. The dimension and bins are selected" @@ -66,12 +71,14 @@ PROGRAM_INFO("Decision Stump", "\n\n" "After training, a decision stump can be saved with the " + PRINT_PARAM_STRING("output_model") + " output parameter. That stump may " - "later be re-used in subsequent calls to this program (or others).", - SEE_ALSO("Decision tree", "#decision_tree"), - SEE_ALSO("Decision stumps on Wikipedia", - "https://en.wikipedia.org/wiki/Decision_stump"), - SEE_ALSO("mlpack::decision_stump::DecisionStump class documentation", - "@doxygen/classmlpack_1_1decision__stump_1_1DecisionStump.html")); + "later be re-used in subsequent calls to this program (or others)."); + +// See also... +BINDING_SEE_ALSO("Decision tree", "#decision_tree"); +BINDING_SEE_ALSO("Decision stumps on Wikipedia", + "https://en.wikipedia.org/wiki/Decision_stump"); +BINDING_SEE_ALSO("mlpack::decision_stump::DecisionStump class documentation", + "@doxygen/classmlpack_1_1decision__stump_1_1DecisionStump.html"); // Datasets we might load. PARAM_MATRIX_IN("training", "The dataset to train on.", "t"); diff --git a/src/mlpack/methods/decision_tree/decision_tree_main.cpp b/src/mlpack/methods/decision_tree/decision_tree_main.cpp index f7b9d55568..61329c9294 100644 --- a/src/mlpack/methods/decision_tree/decision_tree_main.cpp +++ b/src/mlpack/methods/decision_tree/decision_tree_main.cpp @@ -20,13 +20,18 @@ using namespace mlpack::tree; using namespace mlpack::data; using namespace mlpack::util; -PROGRAM_INFO("Decision tree", - // Short description. +// Program Name. +BINDING_NAME("Decision tree"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of an ID3-style decision tree for classification, which" " supports categorical data. Given labeled data with numeric or " "categorical features, a decision tree can be trained and saved; or, an " - "existing decision tree can be used for classification on new points.", - // Long description. + "existing decision tree can be used for classification on new points."); + +// Long description. +BINDING_LONG_DESC( "Train and evaluate using a decision tree. Given a dataset containing " "numeric or categorical features, and associated labels for each point in " "the dataset, this program can train a decision tree on that data." @@ -59,8 +64,10 @@ PROGRAM_INFO("Decision tree", " parameter. Predictions for each test point may be saved via the " + PRINT_PARAM_STRING("predictions") + " output parameter. Class " "probabilities for each prediction may be saved with the " + - PRINT_PARAM_STRING("probabilities") + " output parameter." - "\n\n" + PRINT_PARAM_STRING("probabilities") + " output parameter."); + +// Example. +BINDING_EXAMPLE( "For example, to train a decision tree with a minimum leaf size of 20 on " "the dataset contained in " + PRINT_DATASET("data") + " with labels " + PRINT_DATASET("labels") + ", saving the output model to " + @@ -78,15 +85,17 @@ PROGRAM_INFO("Decision tree", PRINT_DATASET("predictions") + ", one could call " "\n\n" + PRINT_CALL("decision_tree", "input_model", "tree", "test", "test_set", - "test_labels", "test_labels", "predictions", "predictions"), - SEE_ALSO("Decision stump", "#decision_stump"), - SEE_ALSO("Random forest", "#random_forest"), - SEE_ALSO("Decision trees on Wikipedia", - "https://en.wikipedia.org/wiki/Decision_tree_learning"), - SEE_ALSO("Induction of Decision Trees (pdf)", - "https://link.springer.com/content/pdf/10.1007/BF00116251.pdf"), - SEE_ALSO("mlpack::tree::DecisionTree class documentation", - "@doxygen/classmlpack_1_1tree_1_1DecisionTree.html")); + "test_labels", "test_labels", "predictions", "predictions")); + +// See also... +BINDING_SEE_ALSO("Decision stump", "#decision_stump"); +BINDING_SEE_ALSO("Random forest", "#random_forest"); +BINDING_SEE_ALSO("Decision trees on Wikipedia", + "https://en.wikipedia.org/wiki/Decision_tree_learning"); +BINDING_SEE_ALSO("Induction of Decision Trees (pdf)", + "https://link.springer.com/content/pdf/10.1007/BF00116251.pdf"); +BINDING_SEE_ALSO("mlpack::tree::DecisionTree class documentation", + "@doxygen/classmlpack_1_1tree_1_1DecisionTree.html"); // Datasets. PARAM_MATRIX_AND_INFO_IN("training", "Training dataset (may be categorical).", diff --git a/src/mlpack/methods/det/det_main.cpp b/src/mlpack/methods/det/det_main.cpp index e12c7c3995..97193c19e2 100644 --- a/src/mlpack/methods/det/det_main.cpp +++ b/src/mlpack/methods/det/det_main.cpp @@ -19,12 +19,17 @@ using namespace mlpack::det; using namespace mlpack::util; using namespace std; -PROGRAM_INFO("Density Estimation With Density Estimation Trees", - // Short description. +// Program Name. +BINDING_NAME("Density Estimation With Density Estimation Trees"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of density estimation trees for the density estimation " "task. Density estimation trees can be trained or used to predict the " - "density at locations given by query points.", - // Long description. + "density at locations given by query points."); + +// Long description. +BINDING_LONG_DESC( "This program performs a number of functions related to Density Estimation " "Trees. The optimal Density Estimation Tree (DET) can be trained on a set " "of data (specified by " + PRINT_PARAM_STRING("training") + ") using " @@ -54,15 +59,17 @@ PROGRAM_INFO("Density Estimation With Density Estimation Trees", "trained on the given training points, or a tree given as the parameter " + PRINT_PARAM_STRING("input_model") + ". The density estimates for the test" " points may be saved using the " + - PRINT_PARAM_STRING("test_set_estimates") + " output parameter.", - SEE_ALSO("Density estimation tree (DET) tutorial", - "@doxygen/dettutorial.html"), - SEE_ALSO("Density estimation on Wikipedia", - "https://en.wikipedia.org/wiki/Density_estimation"), - SEE_ALSO("Density estimation trees (pdf)", - "http://www.mlpack.org/papers/det.pdf"), - SEE_ALSO("mlpack::tree::DTree class documentation", - "@doxygen/classmlpack_1_1det_1_1DTree.html")); + PRINT_PARAM_STRING("test_set_estimates") + " output parameter."); + +// See also... +BINDING_SEE_ALSO("Density estimation tree (DET) tutorial", + "@doxygen/dettutorial.html"); +BINDING_SEE_ALSO("Density estimation on Wikipedia", + "https://en.wikipedia.org/wiki/Density_estimation"); +BINDING_SEE_ALSO("Density estimation trees (pdf)", + "http://www.mlpack.org/papers/det.pdf"); +BINDING_SEE_ALSO("mlpack::tree::DTree class documentation", + "@doxygen/classmlpack_1_1det_1_1DTree.html"); // Input data files. PARAM_MATRIX_IN("training", "The data set on which to build a density " diff --git a/src/mlpack/methods/emst/emst_main.cpp b/src/mlpack/methods/emst/emst_main.cpp index 179e40f292..c078af4381 100644 --- a/src/mlpack/methods/emst/emst_main.cpp +++ b/src/mlpack/methods/emst/emst_main.cpp @@ -30,11 +30,16 @@ #include "dtb.hpp" -PROGRAM_INFO("Fast Euclidean Minimum Spanning Tree", - // Short description. +// Program Name. +BINDING_NAME("Fast Euclidean Minimum Spanning Tree"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of the Dual-Tree Boruvka algorithm for computing the " - "Euclidean minimum spanning tree of a set of input points.", - // Long description. + "Euclidean minimum spanning tree of a set of input points."); + +// Long description. +BINDING_LONG_DESC( "This program can compute the Euclidean minimum spanning tree of a set of " "input points using the dual-tree Boruvka algorithm." "\n\n" @@ -47,8 +52,10 @@ PROGRAM_INFO("Fast Euclidean Minimum Spanning Tree", "and if the " + PRINT_PARAM_STRING("naive") + " option is given, then " "brute-force search is used (this is typically much slower in low " "dimensions). The leaf size does not affect the results, but it may have " - "some effect on the runtime of the algorithm." - "\n\n" + "some effect on the runtime of the algorithm."); + +// Example. +BINDING_EXAMPLE( "For example, the minimum spanning tree of the input dataset " + PRINT_DATASET("data") + " can be calculated with a leaf size of 20 and " "stored as " + PRINT_DATASET("spanning_tree") + " using the following " @@ -60,14 +67,16 @@ PROGRAM_INFO("Fast Euclidean Minimum Spanning Tree", "The output matrix is a three-dimensional matrix, where each row indicates " "an edge. The first dimension corresponds to the lesser index of the edge;" " the second dimension corresponds to the greater index of the edge; and " - "the third column corresponds to the distance between the two points.", - SEE_ALSO("EMST Tutorial", "@doxygen/emst_tutorial.html"), - SEE_ALSO("Minimum spanning tree on Wikipedia", - "https://en.wikipedia.org/wiki/Minimum_spanning_tree"), - SEE_ALSO("Fast Euclidean Minimum Spanning Tree: Algorithm, Analysis, and " - "Applications (pdf)", "http://www.mlpack.org/papers/emst.pdf"), - SEE_ALSO("mlpack::emst::DualTreeBoruvka class documentation", - "@doxygen/classmlpack_1_1emst_1_1DualTreeBoruvka.html")); + "the third column corresponds to the distance between the two points."); + +// See also... +BINDING_SEE_ALSO("EMST Tutorial", "@doxygen/emst_tutorial.html"); +BINDING_SEE_ALSO("Minimum spanning tree on Wikipedia", + "https://en.wikipedia.org/wiki/Minimum_spanning_tree"); +BINDING_SEE_ALSO("Fast Euclidean Minimum Spanning Tree: Algorithm, Analysis," + " and Applications (pdf)", "http://www.mlpack.org/papers/emst.pdf"); +BINDING_SEE_ALSO("mlpack::emst::DualTreeBoruvka class documentation", + "@doxygen/classmlpack_1_1emst_1_1DualTreeBoruvka.html"); PARAM_MATRIX_IN_REQ("input", "Input data matrix.", "i"); PARAM_MATRIX_OUT("output", "Output data. Stored as an edge list.", "o"); diff --git a/src/mlpack/methods/fastmks/fastmks_main.cpp b/src/mlpack/methods/fastmks/fastmks_main.cpp index 04ca22dace..3b784f6d04 100644 --- a/src/mlpack/methods/fastmks/fastmks_main.cpp +++ b/src/mlpack/methods/fastmks/fastmks_main.cpp @@ -24,20 +24,27 @@ using namespace mlpack::tree; using namespace mlpack::metric; using namespace mlpack::util; -PROGRAM_INFO("FastMKS (Fast Max-Kernel Search)", - // Short description. +// Program Name. +BINDING_NAME("FastMKS (Fast Max-Kernel Search)"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of the single-tree and dual-tree fast max-kernel search" " (FastMKS) algorithm. Given a set of reference points and a set of query" " points, this can find the reference point with maximum kernel value for " - "each query point; trained models can be reused for future queries.", - // Long description. + "each query point; trained models can be reused for future queries."); + +// Long description. +BINDING_LONG_DESC( "This program will find the k maximum kernels of a set of points, " "using a query set and a reference set (which can optionally be the same " "set). More specifically, for each point in the query set, the k points in" " the reference set with maximum kernel evaluations are found. The kernel " "function used is specified with the " + PRINT_PARAM_STRING("kernel") + - " parameter." - "\n\n" + " parameter."); + +// Example. +BINDING_EXAMPLE( "For example, the following command will calculate, for each point in the " "query set " + PRINT_DATASET("query") + ", the five points in the " "reference set " + PRINT_DATASET("reference") + " with maximum kernel " @@ -57,14 +64,16 @@ PROGRAM_INFO("FastMKS (Fast Max-Kernel Search)", "\n\n" "This program performs FastMKS using a cover tree. The base used to build " "the cover tree can be specified with the " + PRINT_PARAM_STRING("base") + - " parameter.", - SEE_ALSO("Fast max-kernel search tutorial (fastmks)", - "@doxygen/fmkstutorial.html"), - SEE_ALSO("k-nearest-neighbor search", "#knn"), - SEE_ALSO("Dual-tree Fast Exact Max-Kernel Search (pdf)", - "http://mlpack.org/papers/fmks.pdf"), - SEE_ALSO("mlpack::fastmks::FastMKS class documentation", - "@doxygen/classmlpack_1_1fastmks_1_1FastMKS.html")); + " parameter."); + +// See also... +BINDING_SEE_ALSO("Fast max-kernel search tutorial (fastmks)", + "@doxygen/fmkstutorial.html"); +BINDING_SEE_ALSO("k-nearest-neighbor search", "#knn"); +BINDING_SEE_ALSO("Dual-tree Fast Exact Max-Kernel Search (pdf)", + "http://mlpack.org/papers/fmks.pdf"); +BINDING_SEE_ALSO("mlpack::fastmks::FastMKS class documentation", + "@doxygen/classmlpack_1_1fastmks_1_1FastMKS.html"); // Model-building parameters. PARAM_MATRIX_IN("reference", "The reference dataset.", "r"); diff --git a/src/mlpack/methods/gmm/gmm_generate_main.cpp b/src/mlpack/methods/gmm/gmm_generate_main.cpp index 4d7c47b74f..aa6e995567 100644 --- a/src/mlpack/methods/gmm/gmm_generate_main.cpp +++ b/src/mlpack/methods/gmm/gmm_generate_main.cpp @@ -19,30 +19,39 @@ using namespace mlpack; using namespace mlpack::gmm; using namespace mlpack::util; -PROGRAM_INFO("GMM Sample Generator", - // Short description. +// Program Name. +BINDING_NAME("GMM Sample Generator"); + +// Short description. +BINDING_SHORT_DESC( "A sample generator for pre-trained GMMs. Given a pre-trained GMM, this " - "can sample new points randomly from that distribution.", - // Long description. + "can sample new points randomly from that distribution."); + +// Long description. +BINDING_LONG_DESC( "This program is able to generate samples from a pre-trained GMM (use " "gmm_train to train a GMM). The pre-trained GMM must be specified with " "the " + PRINT_PARAM_STRING("input_model") + " parameter. The number " "of samples to generate is specified by the " + PRINT_PARAM_STRING("samples") + " parameter. Output samples may be " - "saved with the " + PRINT_PARAM_STRING("output") + " output parameter." - "\n\n" + "saved with the " + PRINT_PARAM_STRING("output") + " output parameter."); + +// Example. +BINDING_EXAMPLE( "The following command can be used to generate 100 samples from the pre-" "trained GMM " + PRINT_MODEL("gmm") + " and store those generated " "samples in " + PRINT_DATASET("samples") + ":" "\n\n" + PRINT_CALL("gmm_generate", "input_model", "gmm", "samples", 100, "output", - "samples"), - SEE_ALSO("@gmm_train", "#gmm_train"), - SEE_ALSO("@gmm_probability", "#gmm_probability"), - SEE_ALSO("Gaussian Mixture Models on Wikipedia", - "https://en.wikipedia.org/wiki/Mixture_model#Gaussian_mixture_model"), - SEE_ALSO("mlpack::gmm::GMM class documentation", - "@doxygen/classmlpack_1_1gmm_1_1GMM.html")); + "samples")); + +// See also... +BINDING_SEE_ALSO("@gmm_train", "#gmm_train"); +BINDING_SEE_ALSO("@gmm_probability", "#gmm_probability"); +BINDING_SEE_ALSO("Gaussian Mixture Models on Wikipedia", + "https://en.wikipedia.org/wiki/Mixture_model#Gaussian_mixture_model"); +BINDING_SEE_ALSO("mlpack::gmm::GMM class documentation", + "@doxygen/classmlpack_1_1gmm_1_1GMM.html"); PARAM_MODEL_IN_REQ(GMM, "input_model", "Input GMM model to generate samples " "from.", "m"); diff --git a/src/mlpack/methods/gmm/gmm_probability_main.cpp b/src/mlpack/methods/gmm/gmm_probability_main.cpp index 15a870ffef..54597696e4 100644 --- a/src/mlpack/methods/gmm/gmm_probability_main.cpp +++ b/src/mlpack/methods/gmm/gmm_probability_main.cpp @@ -19,32 +19,41 @@ using namespace mlpack; using namespace mlpack::gmm; using namespace mlpack::util; -PROGRAM_INFO("GMM Probability Calculator", - // Short description. +// Program Name. +BINDING_NAME("GMM Probability Calculator"); + +// Short description. +BINDING_SHORT_DESC( "A probability calculator for GMMs. Given a pre-trained GMM and a set of " "points, this can compute the probability that each point is from the given" - " GMM.", - // Long description. + " GMM."); + +// Long description. +BINDING_LONG_DESC( "This program calculates the probability that given points came from a " "given GMM (that is, P(X | gmm)). The GMM is specified with the " + PRINT_PARAM_STRING("input_model") + " parameter, and the points are " "specified with the " + PRINT_PARAM_STRING("input") + " parameter. The " "output probabilities may be saved via the " + - PRINT_PARAM_STRING("output") + " output parameter." - "\n\n" + PRINT_PARAM_STRING("output") + " output parameter."); + +// Example. +BINDING_EXAMPLE( "So, for example, to calculate the probabilities of each point in " + PRINT_DATASET("points") + " coming from the pre-trained GMM " + PRINT_MODEL("gmm") + ", while storing those probabilities in " + PRINT_DATASET("probs") + ", the following command could be used:" "\n\n" + PRINT_CALL("gmm_probability", "input_model", "gmm", "input", "points", - "output", "probs"), - SEE_ALSO("@gmm_train", "#gmm_train"), - SEE_ALSO("@gmm_generate", "#gmm_generate"), - SEE_ALSO("Gaussian Mixture Models on Wikipedia", - "https://en.wikipedia.org/wiki/Mixture_model#Gaussian_mixture_model"), - SEE_ALSO("mlpack::gmm::GMM class documentation", - "@doxygen/classmlpack_1_1gmm_1_1GMM.html")); + "output", "probs")); + +// See also... +BINDING_SEE_ALSO("@gmm_train", "#gmm_train"); +BINDING_SEE_ALSO("@gmm_generate", "#gmm_generate"); +BINDING_SEE_ALSO("Gaussian Mixture Models on Wikipedia", + "https://en.wikipedia.org/wiki/Mixture_model#Gaussian_mixture_model"); +BINDING_SEE_ALSO("mlpack::gmm::GMM class documentation", + "@doxygen/classmlpack_1_1gmm_1_1GMM.html"); PARAM_MODEL_IN_REQ(GMM, "input_model", "Input GMM to use as model.", "m"); PARAM_MATRIX_IN_REQ("input", "Input matrix to calculate probabilities of.", diff --git a/src/mlpack/methods/gmm/gmm_train_main.cpp b/src/mlpack/methods/gmm/gmm_train_main.cpp index 2c0f1724d0..0f46816d23 100644 --- a/src/mlpack/methods/gmm/gmm_train_main.cpp +++ b/src/mlpack/methods/gmm/gmm_train_main.cpp @@ -26,12 +26,17 @@ using namespace mlpack::util; using namespace mlpack::kmeans; using namespace std; -PROGRAM_INFO("Gaussian Mixture Model (GMM) Training", - // Short description. +// Program Name. +BINDING_NAME("Gaussian Mixture Model (GMM) Training"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of the EM algorithm for training Gaussian mixture " "models (GMMs). Given a dataset, this can train a GMM for future use " - "with other tools.", - // Long description. + "with other tools."); + +// Long description. +BINDING_LONG_DESC( "This program takes a parametric estimate of a Gaussian mixture model (GMM)" " using the EM algorithm to find the maximum likelihood estimate. The " "model may be saved and reused by other mlpack GMM tools." @@ -77,8 +82,10 @@ PROGRAM_INFO("Gaussian Mixture Model (GMM) Training", "will avoid the checks after each iteration of the EM algorithm which " "ensure that the covariance matrices are positive definite. Specifying " "the flag can cause faster runtime, but may also cause non-positive " - "definite covariance matrices, which will cause the program to crash." - "\n\n" + "definite covariance matrices, which will cause the program to crash."); + +// Example. +BINDING_EXAMPLE( "As an example, to train a 6-Gaussian GMM on the data in " + PRINT_DATASET("data") + " with a maximum of 100 iterations of EM and 3 " "trials, saving the trained GMM to " + PRINT_MODEL("gmm") + ", the " @@ -91,13 +98,15 @@ PROGRAM_INFO("Gaussian Mixture Model (GMM) Training", ", the following command may be used: " "\n\n" + PRINT_CALL("gmm_train", "input_model", "gmm", "input", "data2", - "gaussians", 6, "output_model", "new_gmm"), - SEE_ALSO("@gmm_generate", "#gmm_generate"), - SEE_ALSO("@gmm_probability", "#gmm_probability"), - SEE_ALSO("Gaussian Mixture Models on Wikipedia", - "https://en.wikipedia.org/wiki/Mixture_model#Gaussian_mixture_model"), - SEE_ALSO("mlpack::gmm::GMM class documentation", - "@doxygen/classmlpack_1_1gmm_1_1GMM.html")); + "gaussians", 6, "output_model", "new_gmm")); + +// See also... +BINDING_SEE_ALSO("@gmm_generate", "#gmm_generate"); +BINDING_SEE_ALSO("@gmm_probability", "#gmm_probability"); +BINDING_SEE_ALSO("Gaussian Mixture Models on Wikipedia", + "https://en.wikipedia.org/wiki/Mixture_model#Gaussian_mixture_model"); +BINDING_SEE_ALSO("mlpack::gmm::GMM class documentation", + "@doxygen/classmlpack_1_1gmm_1_1GMM.html"); // Parameters for training. PARAM_MATRIX_IN_REQ("input", "The training data on which the model will be " diff --git a/src/mlpack/methods/hmm/hmm_generate_main.cpp b/src/mlpack/methods/hmm/hmm_generate_main.cpp index 0dfe36241b..579524e36c 100644 --- a/src/mlpack/methods/hmm/hmm_generate_main.cpp +++ b/src/mlpack/methods/hmm/hmm_generate_main.cpp @@ -30,12 +30,17 @@ using namespace mlpack::math; using namespace arma; using namespace std; -PROGRAM_INFO("Hidden Markov Model (HMM) Sequence Generator", - // Short description. +// Program Name. +BINDING_NAME("Hidden Markov Model (HMM) Sequence Generator"); + +// Short description. +BINDING_SHORT_DESC( "A utility to generate random sequences from a pre-trained Hidden Markov " "Model (HMM). The length of the desired sequence can be specified, and a " - "random sequence of observations is returned.", - // Long description. + "random sequence of observations is returned."); + +// Long description. +BINDING_LONG_DESC( "This utility takes an already-trained HMM, specified as the " + PRINT_PARAM_STRING("model") + " parameter, and generates a random " "observation sequence and hidden state sequence based on its parameters. " @@ -45,22 +50,26 @@ PROGRAM_INFO("Hidden Markov Model (HMM) Sequence Generator", " parameter." "\n\n" "The state to start the sequence in may be specified with the " + - PRINT_PARAM_STRING("start_state") + " parameter." - "\n\n" + PRINT_PARAM_STRING("start_state") + " parameter."); + +// Example. +BINDING_EXAMPLE( "For example, to generate a sequence of length 150 from the HMM " + PRINT_MODEL("hmm") + " and save the observation sequence to " + PRINT_DATASET("observations") + " and the hidden state sequence to " + PRINT_DATASET("states") + ", the following command may be used: " "\n\n" + PRINT_CALL("hmm_generate", "model", "hmm", "length", 150, "output", - "observations", "state", "states"), - SEE_ALSO("@hmm_train", "#hmm_train"), - SEE_ALSO("@hmm_loglik", "#hmm_loglik"), - SEE_ALSO("@hmm_viterbi", "#hmm_viterbi"), - SEE_ALSO("Hidden Mixture Models on Wikipedia", - "https://en.wikipedia.org/wiki/Hidden_Markov_model"), - SEE_ALSO("mlpack::hmm::HMM class documentation", - "@doxygen/classmlpack_1_1hmm_1_1HMM.html")); + "observations", "state", "states")); + +// See also... +BINDING_SEE_ALSO("@hmm_train", "#hmm_train"); +BINDING_SEE_ALSO("@hmm_loglik", "#hmm_loglik"); +BINDING_SEE_ALSO("@hmm_viterbi", "#hmm_viterbi"); +BINDING_SEE_ALSO("Hidden Mixture Models on Wikipedia", + "https://en.wikipedia.org/wiki/Hidden_Markov_model"); +BINDING_SEE_ALSO("mlpack::hmm::HMM class documentation", + "@doxygen/classmlpack_1_1hmm_1_1HMM.html"); PARAM_MODEL_IN_REQ(HMMModel, "model", "Trained HMM to generate sequences with.", "m"); diff --git a/src/mlpack/methods/hmm/hmm_loglik_main.cpp b/src/mlpack/methods/hmm/hmm_loglik_main.cpp index c25213b7ad..ed5b587abe 100644 --- a/src/mlpack/methods/hmm/hmm_loglik_main.cpp +++ b/src/mlpack/methods/hmm/hmm_loglik_main.cpp @@ -27,31 +27,40 @@ using namespace mlpack::gmm; using namespace arma; using namespace std; -PROGRAM_INFO("Hidden Markov Model (HMM) Sequence Log-Likelihood", - // Short description. +// Program Name. +BINDING_NAME("Hidden Markov Model (HMM) Sequence Log-Likelihood"); + +// Short description. +BINDING_SHORT_DESC( "A utility for computing the log-likelihood of a sequence for Hidden Markov" " Models (HMMs). Given a pre-trained HMM and an observation sequence, this" " computes and returns the log-likelihood of that sequence being observed " - "from that HMM.", - // Long description. + "from that HMM."); + +// Long description. +BINDING_LONG_DESC( "This utility takes an already-trained HMM, specified with the " + PRINT_PARAM_STRING("input_model") + " parameter, and evaluates the " "log-likelihood of a sequence of observations, given with the " + PRINT_PARAM_STRING("input") + " parameter. The computed log-likelihood is" - " given as output." - "\n\n" + " given as output."); + +// Example. +BINDING_EXAMPLE( "For example, to compute the log-likelihood of the sequence " + PRINT_DATASET("seq") + " with the pre-trained HMM " + PRINT_MODEL("hmm") + ", the following command may be used: " "\n\n" + - PRINT_CALL("hmm_loglik", "input", "seq", "input_model", "hmm"), - SEE_ALSO("@hmm_train", "#hmm_train"), - SEE_ALSO("@hmm_generate", "#hmm_generate"), - SEE_ALSO("@hmm_viterbi", "#hmm_viterbi"), - SEE_ALSO("Hidden Mixture Models on Wikipedia", - "https://en.wikipedia.org/wiki/Hidden_Markov_model"), - SEE_ALSO("mlpack::hmm::HMM class documentation", - "@doxygen/classmlpack_1_1hmm_1_1HMM.html")); + PRINT_CALL("hmm_loglik", "input", "seq", "input_model", "hmm")); + +// See also... +BINDING_SEE_ALSO("@hmm_train", "#hmm_train"); +BINDING_SEE_ALSO("@hmm_generate", "#hmm_generate"); +BINDING_SEE_ALSO("@hmm_viterbi", "#hmm_viterbi"); +BINDING_SEE_ALSO("Hidden Mixture Models on Wikipedia", + "https://en.wikipedia.org/wiki/Hidden_Markov_model"); +BINDING_SEE_ALSO("mlpack::hmm::HMM class documentation", + "@doxygen/classmlpack_1_1hmm_1_1HMM.html"); PARAM_MATRIX_IN_REQ("input", "File containing observations,", "i"); PARAM_MODEL_IN_REQ(HMMModel, "input_model", "File containing HMM.", "m"); diff --git a/src/mlpack/methods/hmm/hmm_train_main.cpp b/src/mlpack/methods/hmm/hmm_train_main.cpp index 6d185f752a..ab51f8e50b 100644 --- a/src/mlpack/methods/hmm/hmm_train_main.cpp +++ b/src/mlpack/methods/hmm/hmm_train_main.cpp @@ -28,12 +28,17 @@ using namespace mlpack::math; using namespace arma; using namespace std; -PROGRAM_INFO("Hidden Markov Model (HMM) Training", - // Short description. +// Program Name. +BINDING_NAME("Hidden Markov Model (HMM) Training"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of training algorithms for Hidden Markov Models (HMMs). " "Given labeled or unlabeled data, an HMM can be trained for further use " - "with other mlpack HMM tools.", - // Long description. + "with other mlpack HMM tools."); + +// Long description. +BINDING_LONG_DESC( "This program allows a Hidden Markov Model to be trained on labeled or " "unlabeled data. It supports four types of HMMs: Discrete HMMs, " "Gaussian HMMs, GMM HMMs, or Diagonal GMM HMMs" @@ -53,14 +58,16 @@ PROGRAM_INFO("Hidden Markov Model (HMM) Training", "\n\n" "Optionally, a pre-created HMM model can be used as a guess for the " "transition matrix and emission probabilities; this is specifiable with " - "--model_file.", - SEE_ALSO("@hmm_generate", "#hmm_generate"), - SEE_ALSO("@hmm_loglik", "#hmm_loglik"), - SEE_ALSO("@hmm_viterbi", "#hmm_viterbi"), - SEE_ALSO("Hidden Mixture Models on Wikipedia", - "https://en.wikipedia.org/wiki/Hidden_Markov_model"), - SEE_ALSO("mlpack::hmm::HMM class documentation", - "@doxygen/classmlpack_1_1hmm_1_1HMM.html")); + "--model_file."); + +// See also... +BINDING_SEE_ALSO("@hmm_generate", "#hmm_generate"); +BINDING_SEE_ALSO("@hmm_loglik", "#hmm_loglik"); +BINDING_SEE_ALSO("@hmm_viterbi", "#hmm_viterbi"); +BINDING_SEE_ALSO("Hidden Mixture Models on Wikipedia", + "https://en.wikipedia.org/wiki/Hidden_Markov_model"); +BINDING_SEE_ALSO("mlpack::hmm::HMM class documentation", + "@doxygen/classmlpack_1_1hmm_1_1HMM.html"); PARAM_STRING_IN_REQ("input_file", "File containing input observations.", "i"); PARAM_STRING_IN("type", "Type of HMM: discrete | gaussian | diag_gmm | gmm.", diff --git a/src/mlpack/methods/hmm/hmm_viterbi_main.cpp b/src/mlpack/methods/hmm/hmm_viterbi_main.cpp index 14db1b6395..ccc9aaa4fd 100644 --- a/src/mlpack/methods/hmm/hmm_viterbi_main.cpp +++ b/src/mlpack/methods/hmm/hmm_viterbi_main.cpp @@ -28,34 +28,43 @@ using namespace mlpack::gmm; using namespace arma; using namespace std; -PROGRAM_INFO("Hidden Markov Model (HMM) Viterbi State Prediction", - // Short description. +// Program Name. +BINDING_NAME("Hidden Markov Model (HMM) Viterbi State Prediction"); + +// Short description. +BINDING_SHORT_DESC( "A utility for computing the most probable hidden state sequence for Hidden" " Markov Models (HMMs). Given a pre-trained HMM and an observed sequence, " "this uses the Viterbi algorithm to compute and return the most probable " - "hidden state sequence.", - // Long description. + "hidden state sequence."); + +// Long description. +BINDING_LONG_DESC( "This utility takes an already-trained HMM, specified as " + PRINT_PARAM_STRING("input_model") + ", and evaluates the most probable " "hidden state sequence of a given sequence of observations (specified as " "'" + PRINT_PARAM_STRING("input") + ", using the Viterbi algorithm. The " "computed state sequence may be saved using the " + - PRINT_PARAM_STRING("output") + " output parameter." - "\n\n" + PRINT_PARAM_STRING("output") + " output parameter."); + +// Example. +BINDING_EXAMPLE( "For example, to predict the state sequence of the observations " + PRINT_DATASET("obs") + " using the HMM " + PRINT_MODEL("hmm") + ", " "storing the predicted state sequence to " + PRINT_DATASET("states") + ", the following command could be used:" "\n\n" + PRINT_CALL("hmm_viterbi", "input", "obs", "input_model", "hmm", "output", - "states"), - SEE_ALSO("@hmm_train", "#hmm_train"), - SEE_ALSO("@hmm_generate", "#hmm_generate"), - SEE_ALSO("@hmm_loglik", "#hmm_loglik"), - SEE_ALSO("Hidden Mixture Models on Wikipedia", - "https://en.wikipedia.org/wiki/Hidden_Markov_model"), - SEE_ALSO("mlpack::hmm::HMM class documentation", - "@doxygen/classmlpack_1_1hmm_1_1HMM.html")); + "states")); + +// See also... +BINDING_SEE_ALSO("@hmm_train", "#hmm_train"); +BINDING_SEE_ALSO("@hmm_generate", "#hmm_generate"); +BINDING_SEE_ALSO("@hmm_loglik", "#hmm_loglik"); +BINDING_SEE_ALSO("Hidden Mixture Models on Wikipedia", + "https://en.wikipedia.org/wiki/Hidden_Markov_model"); +BINDING_SEE_ALSO("mlpack::hmm::HMM class documentation", + "@doxygen/classmlpack_1_1hmm_1_1HMM.html"); PARAM_MATRIX_IN_REQ("input", "Matrix containing observations,", "i"); PARAM_MODEL_IN_REQ(HMMModel, "input_model", "Trained HMM to use.", "m"); diff --git a/src/mlpack/methods/hoeffding_trees/hoeffding_tree_main.cpp b/src/mlpack/methods/hoeffding_trees/hoeffding_tree_main.cpp index 1c016bfb9a..3a02d4c02b 100644 --- a/src/mlpack/methods/hoeffding_trees/hoeffding_tree_main.cpp +++ b/src/mlpack/methods/hoeffding_trees/hoeffding_tree_main.cpp @@ -25,13 +25,18 @@ using namespace mlpack::tree; using namespace mlpack::data; using namespace mlpack::util; -PROGRAM_INFO("Hoeffding trees", - // Short description. +// Program Name. +BINDING_NAME("Hoeffding trees"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of Hoeffding trees, a form of streaming decision tree " "for classification. Given labeled data, a Hoeffding tree can be trained " "and saved for later use, or a pre-trained Hoeffding tree can be used for " - "predicting the classifications of new points.", - // Long description. + "predicting the classifications of new points."); + +// Long description. +BINDING_LONG_DESC( "This program implements Hoeffding trees, a form of streaming decision tree" " suited best for large (or streaming) datasets. This program supports " "both categorical and numeric data. Given an input dataset, this program " @@ -61,8 +66,10 @@ PROGRAM_INFO("Hoeffding trees", " parameter. Predictions for each test point may be saved with the " + PRINT_PARAM_STRING("predictions") + " output parameter, and class " "probabilities for each prediction may be saved with the " + - PRINT_PARAM_STRING("probabilities") + " output parameter." - "\n\n" + PRINT_PARAM_STRING("probabilities") + " output parameter."); + +// Example. +BINDING_EXAMPLE( "For example, to train a Hoeffding tree with confidence 0.99 with data " + PRINT_DATASET("dataset") + ", saving the trained tree to " + PRINT_MODEL("tree") + ", the following command may be used:" @@ -76,13 +83,15 @@ PROGRAM_INFO("Hoeffding trees", PRINT_DATASET("class_probs") + " with the following command: " "\n\n" + PRINT_CALL("hoeffding_tree", "input_model", "tree", "test", "test_set", - "predictions", "predictions", "probabilities", "class_probs"), - SEE_ALSO("@decision_tree", "#decision_tree"), - SEE_ALSO("@random_forest", "#random_forest"), - SEE_ALSO("Mining High-Speed Data Streams (pdf)", - "http://dm.cs.washington.edu/papers/vfdt-kdd00.pdf"), - SEE_ALSO("mlpack::tree::HoeffdingTree class documentation", - "@doxygen/classmlpack_1_1tree_1_1HoeffdingTree.html")); + "predictions", "predictions", "probabilities", "class_probs")); + +// See also... +BINDING_SEE_ALSO("@decision_tree", "#decision_tree"); +BINDING_SEE_ALSO("@random_forest", "#random_forest"); +BINDING_SEE_ALSO("Mining High-Speed Data Streams (pdf)", + "http://dm.cs.washington.edu/papers/vfdt-kdd00.pdf"); +BINDING_SEE_ALSO("mlpack::tree::HoeffdingTree class documentation", + "@doxygen/classmlpack_1_1tree_1_1HoeffdingTree.html"); PARAM_MATRIX_AND_INFO_IN("training", "Training dataset (may be categorical).", "t"); diff --git a/src/mlpack/methods/kde/kde_main.cpp b/src/mlpack/methods/kde/kde_main.cpp index bca333dace..3a9bd919f8 100644 --- a/src/mlpack/methods/kde/kde_main.cpp +++ b/src/mlpack/methods/kde/kde_main.cpp @@ -22,14 +22,18 @@ using namespace mlpack::kde; using namespace mlpack::util; using namespace std; -// Define parameters for the executable. -PROGRAM_INFO("Kernel Density Estimation", - // Short description. +// Program Name. +BINDING_NAME("Kernel Density Estimation"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of kernel density estimation with dual-tree algorithms. " "Given a set of reference points and query points and a kernel function, " "this can estimate the density function at the location of each query point" - " using trees; trees that are built can be saved for later use.", - // Long description. + " using trees; trees that are built can be saved for later use."); + +// Long description. +BINDING_LONG_DESC( "This program performs a Kernel Density Estimation. KDE is a " "non-parametric way of estimating probability density function. " "For each query point the program will estimate its probability density " @@ -68,8 +72,10 @@ PROGRAM_INFO("Kernel Density Estimation", "computations an exact approach would take, this program recurses the tree " "whenever a fraction of the amount of the node's descendant points have " "already been computed. This fraction is set using " + - PRINT_PARAM_STRING("mc_break_coef") + "." - "\n\n" + PRINT_PARAM_STRING("mc_break_coef") + "."); + +// Example. +BINDING_EXAMPLE( "For example, the following will run KDE using the data in " + PRINT_DATASET("ref_data") + " for training and the data in " + PRINT_DATASET("qu_data") + " as query data. It will apply an Epanechnikov " @@ -108,19 +114,20 @@ PROGRAM_INFO("Kernel Density Estimation", 0.2, "kernel", "gaussian", "tree", "kd-tree", "rel_error", 0.05, "predictions", "out_data", "monte_carlo", "", "mc_probability", 0.95, "initial_sample_size", 200, "mc_entry_coef", 3.5, "mc_break_coef", - 0.6) + - "\n\n", - SEE_ALSO("@knn", "#knn"), - SEE_ALSO("Kernel density estimation on Wikipedia", - "https://en.wikipedia.org/wiki/Kernel_density_estimation"), - SEE_ALSO("Tree-Independent Dual-Tree Algorithms", - "https://arxiv.org/pdf/1304.4327.pdf"), - SEE_ALSO("Fast High-dimensional Kernel Summations Using the Monte Carlo " - "Multipole Method", "http://papers.nips.cc/paper/3539-fast-high-" + 0.6)); + +// See also... +BINDING_SEE_ALSO("@knn", "#knn"); +BINDING_SEE_ALSO("Kernel density estimation on Wikipedia", + "https://en.wikipedia.org/wiki/Kernel_density_estimation"); +BINDING_SEE_ALSO("Tree-Independent Dual-Tree Algorithms", + "https://arxiv.org/pdf/1304.4327.pdf"); +BINDING_SEE_ALSO("Fast High-dimensional Kernel Summations Using the Monte Carlo" + " Multipole Method", "http://papers.nips.cc/paper/3539-fast-high-" "dimensional-kernel-summations-using-the-monte-carlo-multipole-method." - "pdf"), - SEE_ALSO("mlpack::kde::KDE C++ class documentation", - "@doxygen/classmlpack_1_1kde_1_1KDE.html")); + "pdf"); +BINDING_SEE_ALSO("mlpack::kde::KDE C++ class documentation", + "@doxygen/classmlpack_1_1kde_1_1KDE.html"); // Required options. PARAM_MATRIX_IN("reference", "Input reference dataset use for KDE.", "r"); diff --git a/src/mlpack/methods/kernel_pca/kernel_pca_main.cpp b/src/mlpack/methods/kernel_pca/kernel_pca_main.cpp index 73f2b043f4..a70c70ef08 100644 --- a/src/mlpack/methods/kernel_pca/kernel_pca_main.cpp +++ b/src/mlpack/methods/kernel_pca/kernel_pca_main.cpp @@ -40,12 +40,17 @@ using namespace mlpack::util; using namespace std; using namespace arma; -PROGRAM_INFO("Kernel Principal Components Analysis", - // Short description. +// Program Name. +BINDING_NAME("Kernel Principal Components Analysis"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of Kernel Principal Components Analysis (KPCA). This " "can be used to perform nonlinear dimensionality reduction or preprocessing" - " on a given dataset.", - // Long description. + " on a given dataset."); + +// Long description. +BINDING_LONG_DESC( "This program performs Kernel Principal Components Analysis (KPCA) on the " "specified dataset with the specified kernel. This will transform the " "data onto the kernel principal components, and optionally reduce the " @@ -55,13 +60,6 @@ PROGRAM_INFO("Kernel Principal Components Analysis", "For the case where a linear kernel is used, this reduces to regular " "PCA." "\n\n" - "For example, the following command will perform KPCA on the dataset " + - PRINT_DATASET("input") + " using the Gaussian kernel, and saving the " - "transformed data to " + PRINT_DATASET("transformed") + ": " - "\n\n" + - PRINT_CALL("kernel_pca", "input", "input", "kernel", "gaussian", "output", - "transformed") + - "\n\n" "The kernels that are supported are listed below:" "\n\n" " * 'linear': the standard linear dot product (same as normal PCA):\n" @@ -98,13 +96,24 @@ PROGRAM_INFO("Kernel Principal Components Analysis", "the kernel matrix; to specify the sampling scheme, the " + PRINT_PARAM_STRING("sampling") + " parameter is used. The " "sampling scheme for the Nystroem method can be chosen from the " - "following list: 'kmeans', 'random', 'ordered'.", - SEE_ALSO("Kernel principal component analysis on Wikipedia", - "https://en.wikipedia.org/wiki/Kernel_principal_component_analysis"), - SEE_ALSO("Kernel Principal Component Analysis (pdf)", - "http://pca.narod.ru/scholkopf_kernel.pdf"), - SEE_ALSO("mlpack::kpca::KernelPCA class documentation", - "@doxygen/classmlpack_1_1kpca_1_1KernelPCA.html")); + "following list: 'kmeans', 'random', 'ordered'."); + +// Example. +BINDING_EXAMPLE( + "For example, the following command will perform KPCA on the dataset " + + PRINT_DATASET("input") + " using the Gaussian kernel, and saving the " + "transformed data to " + PRINT_DATASET("transformed") + ": " + "\n\n" + + PRINT_CALL("kernel_pca", "input", "input", "kernel", "gaussian", "output", + "transformed")); + +// See also... +BINDING_SEE_ALSO("Kernel principal component analysis on Wikipedia", + "https://en.wikipedia.org/wiki/Kernel_principal_component_analysis"); +BINDING_SEE_ALSO("Kernel Principal Component Analysis (pdf)", + "http://pca.narod.ru/scholkopf_kernel.pdf"); +BINDING_SEE_ALSO("mlpack::kpca::KernelPCA class documentation", + "@doxygen/classmlpack_1_1kpca_1_1KernelPCA.html"); PARAM_MATRIX_IN_REQ("input", "Input dataset to perform KPCA on.", "i"); PARAM_MATRIX_OUT("output", "Matrix to save modified dataset to.", "o"); diff --git a/src/mlpack/methods/kmeans/kmeans_main.cpp b/src/mlpack/methods/kmeans/kmeans_main.cpp index 8748ede726..4c7a689aec 100644 --- a/src/mlpack/methods/kmeans/kmeans_main.cpp +++ b/src/mlpack/methods/kmeans/kmeans_main.cpp @@ -27,13 +27,17 @@ using namespace mlpack::kmeans; using namespace mlpack::util; using namespace std; -// Define parameters for the executable. -PROGRAM_INFO("K-Means Clustering", - // Short description. +// Program Name. +BINDING_NAME("K-Means Clustering"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of several strategies for efficient k-means clustering. " "Given a dataset and a value of k, this computes and returns a k-means " - "clustering on that data.", - // Long description. + "clustering on that data."); + +// Long description. +BINDING_LONG_DESC( "This program performs K-Means clustering on the given dataset. It can " "return the learned cluster assignments, and the centroids of the clusters." " Empty clusters are not allowed by default; when a cluster becomes empty," @@ -74,8 +78,10 @@ PROGRAM_INFO("K-Means Clustering", "Initial clustering assignments may be specified using the " + PRINT_PARAM_STRING("initial_centroids") + " parameter, and the maximum " "number of iterations may be specified with the " + - PRINT_PARAM_STRING("max_iterations") + " parameter." - "\n\n" + PRINT_PARAM_STRING("max_iterations") + " parameter."); + +// Example. +BINDING_EXAMPLE( "As an example, to use Hamerly's algorithm to perform k-means clustering " "with k=10 on the dataset " + PRINT_DATASET("data") + ", saving the " "centroids to " + PRINT_DATASET("centroids") + " and the assignments for " @@ -91,21 +97,23 @@ PROGRAM_INFO("K-Means Clustering", "following command may be used:" "\n\n" + PRINT_CALL("kmeans", "input", "data", "initial_centroids", "initial", - "clusters", 10, "max_iterations", 500, "centroid", "final"), - SEE_ALSO("K-Means tutorial", "@doxygen/kmtutorial.html"), - SEE_ALSO("@dbscan", "#dbscan"), - SEE_ALSO("Using the triangle inequality to accelerate k-means (pdf)", - "http://www.aaai.org/Papers/ICML/2003/ICML03-022.pdf"), - SEE_ALSO("Making k-means even faster (pdf)", + "clusters", 10, "max_iterations", 500, "centroid", "final")); + +// See also... +BINDING_SEE_ALSO("K-Means tutorial", "@doxygen/kmtutorial.html"); +BINDING_SEE_ALSO("@dbscan", "#dbscan"); +BINDING_SEE_ALSO("Using the triangle inequality to accelerate k-means (pdf)", + "http://www.aaai.org/Papers/ICML/2003/ICML03-022.pdf"); +BINDING_SEE_ALSO("Making k-means even faster (pdf)", "http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.586.2554" - "&rep=rep1&type=pdf"), - SEE_ALSO("Accelerating exact k-means algorithms with geometric reasoning " - "(pdf)", "http://reports-archive.adm.cs.cmu.edu/anon/anon/usr/ftp/" - "usr0/ftp/2000/CMU-CS-00-105.pdf"), - SEE_ALSO("A dual-tree algorithm for fast k-means clustering with large k " - "(pdf)", "http://www.ratml.org/pub/pdf/2017dual.pdf"), - SEE_ALSO("mlpack::kmeans::KMeans class documentation", - "@doxygen/classmlpack_1_1kmeans_1_1KMeans.html")); + "&rep=rep1&type=pdf"); +BINDING_SEE_ALSO("Accelerating exact k-means algorithms with geometric" + " reasoning (pdf)", "http://reports-archive.adm.cs.cmu.edu/anon/anon" + "/usr/ftp/usr0/ftp/2000/CMU-CS-00-105.pdf"); +BINDING_SEE_ALSO("A dual-tree algorithm for fast k-means clustering with large " + "k (pdf)", "http://www.ratml.org/pub/pdf/2017dual.pdf"); +BINDING_SEE_ALSO("mlpack::kmeans::KMeans class documentation", + "@doxygen/classmlpack_1_1kmeans_1_1KMeans.html"); // Required options. PARAM_MATRIX_IN_REQ("input", "Input dataset to perform clustering on.", "i"); diff --git a/src/mlpack/methods/lars/lars_main.cpp b/src/mlpack/methods/lars/lars_main.cpp index 281b5ee705..202daf4af7 100644 --- a/src/mlpack/methods/lars/lars_main.cpp +++ b/src/mlpack/methods/lars/lars_main.cpp @@ -21,13 +21,18 @@ using namespace mlpack; using namespace mlpack::regression; using namespace mlpack::util; -PROGRAM_INFO("LARS", - // Short description. +// Program Name. +BINDING_NAME("LARS"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of Least Angle Regression (Stagewise/laSso), also known" " as LARS. This can train a LARS/LASSO/Elastic Net model and use that " "model or a pre-trained model to output regression predictions for a test " - "set.", - // Long description. + "set."); + +// Long description. +BINDING_LONG_DESC( "An implementation of LARS: Least Angle Regression (Stagewise/laSso). " "This is a stage-wise homotopy-based algorithm for L1-regularized linear " "regression (LASSO) and L1+L2-regularized linear regression (Elastic Net)." @@ -70,8 +75,10 @@ PROGRAM_INFO("LARS", "trained model or the given input model. Test points can be specified with" " the " + PRINT_PARAM_STRING("test") + " parameter. Predicted responses " "to the test points can be saved with the " + - PRINT_PARAM_STRING("output_predictions") + " output parameter." - "\n\n" + PRINT_PARAM_STRING("output_predictions") + " output parameter."); + +// Example. +BINDING_EXAMPLE( "For example, the following command trains a model on the data " + PRINT_DATASET("data") + " and responses " + PRINT_DATASET("responses") + " with lambda1 set to 0.4 and lambda2 set to 0 (so, LASSO is being " @@ -86,12 +93,14 @@ PROGRAM_INFO("LARS", "and save those responses to " + PRINT_DATASET("test_predictions") + ": " "\n\n" + PRINT_CALL("lars", "input_model", "lasso_model", "test", "test", - "output_predictions", "test_predictions"), - SEE_ALSO("@linear_regression", "#linear_regression"), - SEE_ALSO("Least angle regression (pdf)", - "http://mlpack.org/papers/lars.pdf"), - SEE_ALSO("mlpack::regression::LARS C++ class documentation", - "@doxygen/classmlpack_1_1regression_1_1LARS.html")); + "output_predictions", "test_predictions")); + +// See also... +BINDING_SEE_ALSO("@linear_regression", "#linear_regression"); +BINDING_SEE_ALSO("Least angle regression (pdf)", + "http://mlpack.org/papers/lars.pdf"); +BINDING_SEE_ALSO("mlpack::regression::LARS C++ class documentation", + "@doxygen/classmlpack_1_1regression_1_1LARS.html"); PARAM_TMATRIX_IN("input", "Matrix of covariates (X).", "i"); PARAM_MATRIX_IN("responses", "Matrix of responses/observations (y).", "r"); diff --git a/src/mlpack/methods/linear_regression/linear_regression_main.cpp b/src/mlpack/methods/linear_regression/linear_regression_main.cpp index befe22f351..13fcacc386 100644 --- a/src/mlpack/methods/linear_regression/linear_regression_main.cpp +++ b/src/mlpack/methods/linear_regression/linear_regression_main.cpp @@ -21,13 +21,18 @@ using namespace mlpack::util; using namespace arma; using namespace std; -PROGRAM_INFO("Simple Linear Regression and Prediction", - // Short description. +// Program Name. +BINDING_NAME("Simple Linear Regression and Prediction"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of simple linear regression and ridge regression using " "ordinary least squares. Given a dataset and responses, a model can be " "trained and saved for later use, or a pre-trained model can be used to " - "output regression predictions for a test set.", - // Long description. + "output regression predictions for a test set."); + +// Long description. +BINDING_LONG_DESC( "An implementation of simple linear regression and simple ridge regression " "using ordinary least squares. This solves the problem" "\n\n" @@ -53,8 +58,10 @@ PROGRAM_INFO("Simple Linear Regression and Prediction", "and the predicted responses y' may be saved with the " + PRINT_PARAM_STRING("output_predictions") + " output parameter. This type " "of regression is related to least-angle regression, which mlpack " - "implements as the 'lars' program." - "\n\n" + "implements as the 'lars' program."); + +// Example. +BINDING_EXAMPLE( "For example, to run a linear regression on the dataset " + PRINT_DATASET("X") + " with responses " + PRINT_DATASET("y") + ", saving " "the trained model to " + PRINT_MODEL("lr_model") + ", the following " @@ -69,13 +76,17 @@ PROGRAM_INFO("Simple Linear Regression and Prediction", "used:" "\n\n" + PRINT_CALL("linear_regression", "input_model", "lr_model", "test", "X_test", - "output_predictions", "X_test_responses"), - SEE_ALSO("Linear/ridge regression tutorial", "@doxygen/lrtutorial.html"), - SEE_ALSO("@lars", "#lars"), - SEE_ALSO("Linear regression on Wikipedia", - "https://en.wikipedia.org/wiki/Linear_regression"), - SEE_ALSO("mlpack::regression::LinearRegression C++ class documentation", - "@doxygen/classmlpack_1_1regression_1_1LinearRegression.html")); + "output_predictions", "X_test_responses")); + +// See also... +BINDING_SEE_ALSO("Linear/ridge regression tutorial", + "@doxygen/lrtutorial.html"); +BINDING_SEE_ALSO("@lars", "#lars"); +BINDING_SEE_ALSO("Linear regression on Wikipedia", + "https://en.wikipedia.org/wiki/Linear_regression"); +BINDING_SEE_ALSO("mlpack::regression::LinearRegression C++ class " + "documentation", + "@doxygen/classmlpack_1_1regression_1_1LinearRegression.html"); PARAM_MATRIX_IN("training", "Matrix containing training set X (regressors).", "t"); diff --git a/src/mlpack/methods/linear_svm/linear_svm_main.cpp b/src/mlpack/methods/linear_svm/linear_svm_main.cpp index 1857902008..bd328fe419 100644 --- a/src/mlpack/methods/linear_svm/linear_svm_main.cpp +++ b/src/mlpack/methods/linear_svm/linear_svm_main.cpp @@ -23,12 +23,17 @@ using namespace mlpack; using namespace mlpack::svm; using namespace mlpack::util; -PROGRAM_INFO("Linear SVM is an L2-regularized support vector machine.", - // Short description. +// Program Name. +BINDING_NAME("Linear SVM is an L2-regularized support vector machine."); + +// Short description. +BINDING_SHORT_DESC( "An implementation of linear SVM for multiclass classification. " "Given labeled data, a model can be trained and saved for " - "future use; or, a pre-trained model can be used to classify new points.", - // Long description. + "future use; or, a pre-trained model can be used to classify new points."); + +// Long description. +BINDING_LONG_DESC( "An implementation of linear SVMs that uses either L-BFGS or parallel SGD" " (stochastic gradient descent) to train the model." "\n\n" @@ -77,8 +82,10 @@ PROGRAM_INFO("Linear SVM is an L2-regularized support vector machine.", "so long as an existing linear SVM model is given with the " + PRINT_PARAM_STRING("input_model") + " parameter. The output predictions " "from the linear SVM model may be saved with the " + - PRINT_PARAM_STRING("predictions") + " parameter." + - "\n\n" + PRINT_PARAM_STRING("predictions") + " parameter."); + +// Example. +BINDING_EXAMPLE( "As an example, to train a LinaerSVM on the data '" + PRINT_DATASET("data") + "' with labels '" + PRINT_DATASET("labels") + "' " "with L2 regularization of 0.1, saving the model to '" + @@ -93,13 +100,15 @@ PROGRAM_INFO("Linear SVM is an L2-regularized support vector machine.", PRINT_DATASET("predictions") + "', the following command may be used: " "\n\n" + PRINT_CALL("linear_svm", "input_model", "lsvm_model", "test", "test", - "predictions", "predictions"), - SEE_ALSO("@random_forest", "#random_forest"), - SEE_ALSO("@logistic_regression", "#logistic_regression"), - SEE_ALSO("LinearSVM on Wikipedia", - "https://en.wikipedia.org/wiki/Support-vector_machine"), - SEE_ALSO("mlpack::svm::LinearSVM C++ class documentation", - "@doxygen/classmlpack_1_1svm_1_1LinearSVM.html")); + "predictions", "predictions")); + +// See also... +BINDING_SEE_ALSO("@random_forest", "#random_forest"); +BINDING_SEE_ALSO("@logistic_regression", "#logistic_regression"); +BINDING_SEE_ALSO("LinearSVM on Wikipedia", + "https://en.wikipedia.org/wiki/Support-vector_machine"); +BINDING_SEE_ALSO("mlpack::svm::LinearSVM C++ class documentation", + "@doxygen/classmlpack_1_1svm_1_1LinearSVM.html"); // Training parameters. PARAM_MATRIX_IN("training", "A matrix containing the training set (the matrix " diff --git a/src/mlpack/methods/lmnn/lmnn_main.cpp b/src/mlpack/methods/lmnn/lmnn_main.cpp index 0410e458f2..2aa49b6321 100644 --- a/src/mlpack/methods/lmnn/lmnn_main.cpp +++ b/src/mlpack/methods/lmnn/lmnn_main.cpp @@ -21,14 +21,18 @@ #include -// Define parameters. -PROGRAM_INFO("Large Margin Nearest Neighbors (LMNN)", - // Short description. +// Program Name. +BINDING_NAME("Large Margin Nearest Neighbors (LMNN)"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of Large Margin Nearest Neighbors (LMNN), a distance " "learning technique. Given a labeled dataset, this learns a transformation" " of the data that improves k-nearest-neighbor performance; this can be " - "useful as a preprocessing step.", - // Long description. + "useful as a preprocessing step."); + +// Long description. +BINDING_LONG_DESC( "This program implements Large Margin Nearest Neighbors, a distance " "learning technique. The method seeks to improve k-nearest-neighbor " "classification on a dataset. The method employes the strategy of " @@ -111,8 +115,10 @@ PROGRAM_INFO("Large Margin Nearest Neighbors (LMNN)", "literature on L-BFGS. In addition, a normalized starting point can be " "used by specifying the " + PRINT_PARAM_STRING("normalize") + " parameter." "\n\n" - "By default, the AMSGrad optimizer is used." - "\n\n" + "By default, the AMSGrad optimizer is used."); + +// Example. +BINDING_EXAMPLE( "Example - Let's say we want to learn distance on iris dataset with " "number of targets as 3 using BigBatch_SGD optimizer. A simple call for " "the same will look like: " @@ -124,15 +130,17 @@ PROGRAM_INFO("Large Margin Nearest Neighbors (LMNN)", "with dataset having labels as last column can be made as: " "\n\n" + PRINT_CALL("mlpack_lmnn", "input", "letter_recognition", "k", 5, - "range", 10, "regularization", 0.4, "output", "output"), - SEE_ALSO("@nca", "#nca"), - SEE_ALSO("Large margin nearest neighbor on Wikipedia", - "https://en.wikipedia.org/wiki/Large_margin_nearest_neighbor"), - SEE_ALSO("Distance metric learning for large margin nearest neighbor " + "range", 10, "regularization", 0.4, "output", "output")); + +// See also... +BINDING_SEE_ALSO("@nca", "#nca"); +BINDING_SEE_ALSO("Large margin nearest neighbor on Wikipedia", + "https://en.wikipedia.org/wiki/Large_margin_nearest_neighbor"); +BINDING_SEE_ALSO("Distance metric learning for large margin nearest neighbor " "classification (pdf)", "http://papers.nips.cc/paper/2795-distance-" - "metric-learning-for-large-margin-nearest-neighbor-classification.pdf"), - SEE_ALSO("mlpack::lmnn::LMNN C++ class documentation", - "@doxygen/classmlpack_1_1lmnn_1_1LMNN.html")); + "metric-learning-for-large-margin-nearest-neighbor-classification.pdf"); +BINDING_SEE_ALSO("mlpack::lmnn::LMNN C++ class documentation", + "@doxygen/classmlpack_1_1lmnn_1_1LMNN.html"); PARAM_MATRIX_IN_REQ("input", "Input dataset to run LMNN on.", "i"); PARAM_MATRIX_IN("distance", "Initial distance matrix to be used as " diff --git a/src/mlpack/methods/local_coordinate_coding/local_coordinate_coding_main.cpp b/src/mlpack/methods/local_coordinate_coding/local_coordinate_coding_main.cpp index 7b92945902..54dd2d73e5 100644 --- a/src/mlpack/methods/local_coordinate_coding/local_coordinate_coding_main.cpp +++ b/src/mlpack/methods/local_coordinate_coding/local_coordinate_coding_main.cpp @@ -23,13 +23,18 @@ using namespace mlpack::lcc; using namespace mlpack::sparse_coding; // For NothingInitializer. using namespace mlpack::util; -PROGRAM_INFO("Local Coordinate Coding", - // Short description. +// Program Name. +BINDING_NAME("Local Coordinate Coding"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of Local Coordinate Coding (LCC), a data transformation " "technique. Given input data, this transforms each point to be expressed " "as a linear combination of a few points in the dataset; once an LCC model " - "is trained, it can be used to transform points later also.", - // Long description. + "is trained, it can be used to transform points later also."); + +// Long description. +BINDING_LONG_DESC( "An implementation of Local Coordinate Coding (LCC), which " "codes data that approximately lives on a manifold using a variation of l1-" "norm regularized sparse coding. Given a dense data matrix X with n points" @@ -44,8 +49,10 @@ PROGRAM_INFO("Local Coordinate Coding", "\n\n" "The coding is found with an algorithm which alternates between a " "dictionary step, which updates the dictionary D, and a coding step, which " - "updates the coding matrix Z." - "\n\n" + "updates the coding matrix Z."); + +// Example. +BINDING_EXAMPLE( "To run this program, the input matrix X must be specified (with -i), along" " with the number of atoms in the dictionary (-k). An initial dictionary " "may also be specified with the " + @@ -73,13 +80,15 @@ PROGRAM_INFO("Local Coordinate Coding", "be used:" "\n\n" + PRINT_CALL("local_coordinate_coding", "input_model", "lcc_model", "test", - "points", "codes", "new_codes"), - SEE_ALSO("@sparse_coding", "#sparse_coding"), - SEE_ALSO("Nonlinear learning using local coordinate coding (pdf)", + "points", "codes", "new_codes")); + +// See also... +BINDING_SEE_ALSO("@sparse_coding", "#sparse_coding"); +BINDING_SEE_ALSO("Nonlinear learning using local coordinate coding (pdf)", "https://papers.nips.cc/paper/3875-nonlinear-learning-using-local-" - "coordinate-coding.pdf"), - SEE_ALSO("mlpack::lcc::LocalCoordinateCoding C++ class documentation", - "@doxygen/classmlpack_1_1lcc_1_1LocalCoordinateCoding.html")); + "coordinate-coding.pdf"); +BINDING_SEE_ALSO("mlpack::lcc::LocalCoordinateCoding C++ class documentation", + "@doxygen/classmlpack_1_1lcc_1_1LocalCoordinateCoding.html"); // Training parameters. PARAM_MATRIX_IN("training", "Matrix of training data (X).", "t"); diff --git a/src/mlpack/methods/logistic_regression/logistic_regression.hpp b/src/mlpack/methods/logistic_regression/logistic_regression.hpp index ba03114757..677f3faf84 100644 --- a/src/mlpack/methods/logistic_regression/logistic_regression.hpp +++ b/src/mlpack/methods/logistic_regression/logistic_regression.hpp @@ -140,12 +140,9 @@ class LogisticRegression * Using this overload allows configuring the instantiated optimizer before * training is performed. * - * Note that the initial point of the optimizer - * (optimizer.Function().GetInitialPoint()) will be used as the initial point - * of the optimization, overwriting any existing trained model. If you don't - * want to overwrite the existing model, set - * optimizer.Function().GetInitialPoint() to the current parameters vector, - * accessible via Parameters(). + * This will use the existing model parameters as a starting point for the + * optimization. If this is not what you want, then you should access the + * parameters vector directly with Parameters() and modify it as desired. * * @tparam OptimizerType Type of optimizer to use to train the model. * @tparam CallbackTypes Types of Callback Functions. diff --git a/src/mlpack/methods/logistic_regression/logistic_regression_function.hpp b/src/mlpack/methods/logistic_regression/logistic_regression_function.hpp index 692796d7a0..636aa4d601 100644 --- a/src/mlpack/methods/logistic_regression/logistic_regression_function.hpp +++ b/src/mlpack/methods/logistic_regression/logistic_regression_function.hpp @@ -41,24 +41,6 @@ class LogisticRegressionFunction const arma::Row& responses, const double lambda = 0); - /** - * Creates the LogisticRegressionFunction with initialPoint. - * - * @param predictors The matrix of data points. - * @param responses The measured data for each point in predictors. - * @param initialPoint Point from which to start the optimization. - * @param lambda Regularization constant for ridge regression. - */ - LogisticRegressionFunction(const MatType& predictors, - const arma::Row& responses, - const arma::vec& initialPoint, - const double lambda = 0); - - //! Return the initial point for the optimization. - const arma::mat& InitialPoint() const { return initialPoint; } - //! Modify the initial point for the optimization. - arma::mat& InitialPoint() { return initialPoint; } - //! Return the regularization parameter (lambda). const double& Lambda() const { return lambda; } //! Modify the regularization parameter (lambda). @@ -170,9 +152,6 @@ class LogisticRegressionFunction GradType& gradient, const size_t batchSize = 1) const; - //! Return the initial point for the optimization. - const arma::mat& GetInitialPoint() const { return initialPoint; } - //! Return the number of separable functions (the number of predictor points). size_t NumFunctions() const { return predictors.n_cols; } @@ -180,8 +159,6 @@ class LogisticRegressionFunction size_t NumFeatures() const { return predictors.n_rows + 1; } private: - //! The initial point, from which to start the optimization. - arma::mat initialPoint; //! The matrix of data points (predictors). This is an alias until shuffling //! is done. MatType predictors; diff --git a/src/mlpack/methods/logistic_regression/logistic_regression_function_impl.hpp b/src/mlpack/methods/logistic_regression/logistic_regression_function_impl.hpp index 1b37ba070b..a28a1d38d4 100644 --- a/src/mlpack/methods/logistic_regression/logistic_regression_function_impl.hpp +++ b/src/mlpack/methods/logistic_regression/logistic_regression_function_impl.hpp @@ -31,8 +31,6 @@ LogisticRegressionFunction::LogisticRegressionFunction( false)), lambda(lambda) { - initialPoint = arma::rowvec(predictors.n_rows + 1, arma::fill::zeros); - // Sanity check. if (responses.n_elem != predictors.n_cols) { @@ -43,25 +41,6 @@ LogisticRegressionFunction::LogisticRegressionFunction( } } -template -LogisticRegressionFunction::LogisticRegressionFunction( - const MatType& predictors, - const arma::Row& responses, - const arma::vec& initialPoint, - const double lambda) : - initialPoint(initialPoint), - // We promise to be well-behaved... the elements won't be modified. - predictors(math::MakeAlias(const_cast(predictors), false)), - responses(math::MakeAlias(const_cast&>(responses), - false)), - lambda(lambda) -{ - // To check if initialPoint is compatible with predictors. - if (initialPoint.n_rows != (predictors.n_rows + 1) || - initialPoint.n_cols != 1) - this->initialPoint = arma::rowvec(predictors.n_rows + 1, arma::fill::zeros); -} - /** * Shuffle the datapoints. */ diff --git a/src/mlpack/methods/logistic_regression/logistic_regression_impl.hpp b/src/mlpack/methods/logistic_regression/logistic_regression_impl.hpp index cdbad518fb..738e0b1355 100644 --- a/src/mlpack/methods/logistic_regression/logistic_regression_impl.hpp +++ b/src/mlpack/methods/logistic_regression/logistic_regression_impl.hpp @@ -87,8 +87,8 @@ double LogisticRegression::Train( lambda); // Set size of parameters vector according to the input data received. - parameters = arma::rowvec(predictors.n_rows + 1, arma::fill::zeros); - errorFunction.InitialPoint() = parameters; + if (parameters.n_elem != predictors.n_rows + 1) + parameters = arma::rowvec(predictors.n_rows + 1, arma::fill::zeros); Timer::Start("logistic_regression_optimization"); const double out = optimizer.Optimize(errorFunction, parameters, diff --git a/src/mlpack/methods/logistic_regression/logistic_regression_main.cpp b/src/mlpack/methods/logistic_regression/logistic_regression_main.cpp index 76254bf704..408385875e 100644 --- a/src/mlpack/methods/logistic_regression/logistic_regression_main.cpp +++ b/src/mlpack/methods/logistic_regression/logistic_regression_main.cpp @@ -22,12 +22,17 @@ using namespace mlpack; using namespace mlpack::regression; using namespace mlpack::util; -PROGRAM_INFO("L2-regularized Logistic Regression and Prediction", - // Short description. +// Program Name. +BINDING_NAME("L2-regularized Logistic Regression and Prediction"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of L2-regularized logistic regression for two-class " "classification. Given labeled data, a model can be trained and saved for " - "future use; or, a pre-trained model can be used to classify new points.", - // Long description. + "future use; or, a pre-trained model can be used to classify new points."); + +// Long description. +BINDING_LONG_DESC( "An implementation of L2-regularized logistic regression using either the " "L-BFGS optimizer or SGD (stochastic gradient descent). This solves the " "regression problem" @@ -92,8 +97,11 @@ PROGRAM_INFO("L2-regularized Logistic Regression and Prediction", "\n\n" "This implementation of logistic regression does not support the general " "multi-class case but instead only the two-class case. Any labels must " - "be either 0 or 1. For more classes, see the softmax_regression program." - "\n\n" + "be either 0 or 1. For more classes, see the softmax_regression " + "program."); + +// Example. +BINDING_EXAMPLE( "As an example, to train a logistic regression model on the data '" + PRINT_DATASET("data") + "' with labels '" + PRINT_DATASET("labels") + "' " "with L2 regularization of 0.1, saving the model to '" + @@ -107,13 +115,16 @@ PROGRAM_INFO("L2-regularized Logistic Regression and Prediction", PRINT_DATASET("predictions") + "', the following command may be used: " "\n\n" + PRINT_CALL("logistic_regression", "input_model", "lr_model", "test", "test", - "output", "predictions"), - SEE_ALSO("@softmax_regression", "#softmax_regression"), - SEE_ALSO("@random_forest", "#random_forest"), - SEE_ALSO("Logistic regression on Wikipedia", - "https://en.wikipedia.org/wiki/Logistic_regression"), - SEE_ALSO("mlpack::regression::LogisticRegression C++ class documentation", - "@doxygen/classmlpack_1_1regression_1_1LogisticRegression.html")); + "output", "predictions")); + +// See also... +BINDING_SEE_ALSO("@softmax_regression", "#softmax_regression"); +BINDING_SEE_ALSO("@random_forest", "#random_forest"); +BINDING_SEE_ALSO("Logistic regression on Wikipedia", + "https://en.wikipedia.org/wiki/Logistic_regression"); +BINDING_SEE_ALSO("mlpack::regression::LogisticRegression C++ class " + "documentation", + "@doxygen/classmlpack_1_1regression_1_1LogisticRegression.html"); // Training parameters. PARAM_MATRIX_IN("training", "A matrix containing the training set (the matrix " diff --git a/src/mlpack/methods/lsh/lsh_main.cpp b/src/mlpack/methods/lsh/lsh_main.cpp index 7a4203eb0c..7f36100311 100644 --- a/src/mlpack/methods/lsh/lsh_main.cpp +++ b/src/mlpack/methods/lsh/lsh_main.cpp @@ -23,20 +23,26 @@ using namespace mlpack; using namespace mlpack::neighbor; using namespace mlpack::util; -// Information about the program itself. -PROGRAM_INFO("K-Approximate-Nearest-Neighbor Search with LSH", - // Short description. +// Program Name. +BINDING_NAME("K-Approximate-Nearest-Neighbor Search with LSH"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of approximate k-nearest-neighbor search with " "locality-sensitive hashing (LSH). Given a set of reference points and a " "set of query points, this will compute the k approximate nearest neighbors" " of each query point in the reference set; models can be saved for future " - "use.", - // Long description. + "use."); + +// Long description. +BINDING_LONG_DESC( "This program will calculate the k approximate-nearest-neighbors of a set " "of points using locality-sensitive hashing. You may specify a separate set" " of reference points and query points, or just a reference set which will " - "be used as both the reference and query set. " - "\n\n" + "be used as both the reference and query set. "); + +// Example. +BINDING_EXAMPLE( "For example, the following will return 5 neighbors from the data for each " "point in " + PRINT_DATASET("input") + " and store the distances in " + PRINT_DATASET("distances") + " and the neighbors in " + @@ -56,15 +62,17 @@ PROGRAM_INFO("K-Approximate-Nearest-Neighbor Search with LSH", " parameter can be specified to set the random seed." "\n\n" "This program also has many other parameters to control its functionality;" - " see the parameter-specific documentation for more information.", - SEE_ALSO("@knn", "#knn"), - SEE_ALSO("@krann", "#krann"), - SEE_ALSO("Locality-sensitive hashing on Wikipedia", - "https://en.wikipedia.org/wiki/Locality-sensitive_hashing"), - SEE_ALSO("Locality-sensitive hashing scheme based on p-stable distributions" - " (pdf)", "http://mlpack.org/papers/lsh.pdf"), - SEE_ALSO("mlpack::neighbor::LSHSearch C++ class documentation", - "@doxygen/classmlpack_1_1neighbor_1_1LSHSearch.html")); + " see the parameter-specific documentation for more information."); + +// See also... +BINDING_SEE_ALSO("@knn", "#knn"); +BINDING_SEE_ALSO("@krann", "#krann"); +BINDING_SEE_ALSO("Locality-sensitive hashing on Wikipedia", + "https://en.wikipedia.org/wiki/Locality-sensitive_hashing"); +BINDING_SEE_ALSO("Locality-sensitive hashing scheme based on p-stable" + " distributions(pdf)", "http://mlpack.org/papers/lsh.pdf"); +BINDING_SEE_ALSO("mlpack::neighbor::LSHSearch C++ class documentation", + "@doxygen/classmlpack_1_1neighbor_1_1LSHSearch.html"); // Define our input parameters that this program will take. PARAM_MATRIX_IN("reference", "Matrix containing the reference dataset.", "r"); diff --git a/src/mlpack/methods/mean_shift/mean_shift_main.cpp b/src/mlpack/methods/mean_shift/mean_shift_main.cpp index acf503f750..b38a86a364 100644 --- a/src/mlpack/methods/mean_shift/mean_shift_main.cpp +++ b/src/mlpack/methods/mean_shift/mean_shift_main.cpp @@ -22,13 +22,17 @@ using namespace mlpack::kernel; using namespace mlpack::util; using namespace std; -// Define parameters for the executable. -PROGRAM_INFO("Mean Shift Clustering", - // Short description. +// Program Name. +BINDING_NAME("Mean Shift Clustering"); + +// Short description. +BINDING_SHORT_DESC( "A fast implementation of mean-shift clustering using dual-tree range " "search. Given a dataset, this uses the mean shift algorithm to produce " - "and return a clustering of the data.", - // Long description. + "and return a clustering of the data."); + +// Long description. +BINDING_LONG_DESC( "This program performs mean shift clustering on the given dataset, storing " "the learned cluster assignments either as a column of labels in the input " "dataset or separately." @@ -42,22 +46,26 @@ PROGRAM_INFO("Mean Shift Clustering", "\n\n" "The output labels may be saved with the " + PRINT_PARAM_STRING("output") + " output parameter and the centroids of each cluster may be saved with the" - " " + PRINT_PARAM_STRING("centroid") + " output parameter." - "\n\n" + " " + PRINT_PARAM_STRING("centroid") + " output parameter."); + +// Example. +BINDING_EXAMPLE( "For example, to run mean shift clustering on the dataset " + PRINT_DATASET("data") + " and store the centroids to " + PRINT_DATASET("centroids") + ", the following command may be used: " "\n\n" + - PRINT_CALL("mean_shift", "input", "data", "centroid", "centroids"), - SEE_ALSO("@kmeans", "#kmeans"), - SEE_ALSO("@dbscan", "#dbscan"), - SEE_ALSO("Mean shift on Wikipedia", - "https://en.wikipedia.org/wiki/Mean_shift"), - SEE_ALSO("Mean Shift, Mode Seeking, and Clustering (pdf)", + PRINT_CALL("mean_shift", "input", "data", "centroid", "centroids")); + +// See also... +BINDING_SEE_ALSO("@kmeans", "#kmeans"); +BINDING_SEE_ALSO("@dbscan", "#dbscan"); +BINDING_SEE_ALSO("Mean shift on Wikipedia", + "https://en.wikipedia.org/wiki/Mean_shift"); +BINDING_SEE_ALSO("Mean Shift, Mode Seeking, and Clustering (pdf)", "http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.510.1222" - "&rep=rep1&type=pdf"), - SEE_ALSO("mlpack::mean_shift::MeanShift C++ class documentation", - "@doxygen/classmlpack_1_1meanshift_1_1MeanShift.html")); + "&rep=rep1&type=pdf"); +BINDING_SEE_ALSO("mlpack::mean_shift::MeanShift C++ class documentation", + "@doxygen/classmlpack_1_1meanshift_1_1MeanShift.html"); // Required options. PARAM_MATRIX_IN_REQ("input", "Input dataset to perform clustering on.", "i"); diff --git a/src/mlpack/methods/mvu/mvu_main.cpp b/src/mlpack/methods/mvu/mvu_main.cpp index a62dfd9d5c..e61fc9eacf 100644 --- a/src/mlpack/methods/mvu/mvu_main.cpp +++ b/src/mlpack/methods/mvu/mvu_main.cpp @@ -15,7 +15,11 @@ #include #include "mvu.hpp" -PROGRAM_INFO("Maximum Variance Unfolding (MVU)", "This program implements " +// Program Name. +BINDING_NAME("Maximum Variance Unfolding (MVU)"); + +// Long description. +BINDING_LONG_DESC("This program implements " "Maximum Variance Unfolding, a nonlinear dimensionality reduction " "technique. The method minimizes dimensionality by unfolding a manifold " "such that the distances to the nearest neighbors of each point are held " diff --git a/src/mlpack/methods/naive_bayes/nbc_main.cpp b/src/mlpack/methods/naive_bayes/nbc_main.cpp index 5d04c5434f..d3b5934490 100644 --- a/src/mlpack/methods/naive_bayes/nbc_main.cpp +++ b/src/mlpack/methods/naive_bayes/nbc_main.cpp @@ -25,12 +25,17 @@ using namespace mlpack::util; using namespace std; using namespace arma; -PROGRAM_INFO("Parametric Naive Bayes Classifier", - // Short description. +// Program Name. +BINDING_NAME("Parametric Naive Bayes Classifier"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of the Naive Bayes Classifier, used for classification. " "Given labeled data, an NBC model can be trained and saved, or, a " - "pre-trained model can be used for classification.", - // Long description. + "pre-trained model can be used for classification."); + +// Long description. +BINDING_LONG_DESC( "This program trains the Naive Bayes classifier on the given labeled " "training set, or loads a model from the given model file, and then may use" " that trained model to classify the points in a given test set." @@ -60,8 +65,10 @@ PROGRAM_INFO("Parametric Naive Bayes Classifier", "Note: the " + PRINT_PARAM_STRING("output") + " and " + PRINT_PARAM_STRING("output_probs") + " parameters are deprecated and will " "be removed in mlpack 4.0.0. Use " + PRINT_PARAM_STRING("predictions") + - " and " + PRINT_PARAM_STRING("probabilities") + " instead." - "\n\n" + " and " + PRINT_PARAM_STRING("probabilities") + " instead."); + +// Example. +BINDING_EXAMPLE( "For example, to train a Naive Bayes classifier on the dataset " + PRINT_DATASET("data") + " with labels " + PRINT_DATASET("labels") + " " "and save the model to " + PRINT_MODEL("nbc_model") + ", the following " @@ -76,14 +83,16 @@ PROGRAM_INFO("Parametric Naive Bayes Classifier", "may be used:" "\n\n" + PRINT_CALL("nbc", "input_model", "nbc_model", "test", "test_set", "output", - "predictions"), - SEE_ALSO("@softmax_regression", "#softmax_regression"), - SEE_ALSO("@random_forest", "#random_forest"), - SEE_ALSO("Naive Bayes classifier on Wikipedia", - "https://en.wikipedia.org/wiki/Naive_Bayes_classifier"), - SEE_ALSO("mlpack::naive_bayes::NaiveBayesClassifier C++ class " + "predictions")); + +// See also... +BINDING_SEE_ALSO("@softmax_regression", "#softmax_regression"); +BINDING_SEE_ALSO("@random_forest", "#random_forest"); +BINDING_SEE_ALSO("Naive Bayes classifier on Wikipedia", + "https://en.wikipedia.org/wiki/Naive_Bayes_classifier"); +BINDING_SEE_ALSO("mlpack::naive_bayes::NaiveBayesClassifier C++ class " "documentation", "@doxygen/classmlpack_1_1naive__bayes_1_1" - "NaiveBayesClassifier.html")); + "NaiveBayesClassifier.html"); // A struct for saving the model with mappings. struct NBCModel diff --git a/src/mlpack/methods/nca/nca_main.cpp b/src/mlpack/methods/nca/nca_main.cpp index 2dee1c4def..ba4447b831 100644 --- a/src/mlpack/methods/nca/nca_main.cpp +++ b/src/mlpack/methods/nca/nca_main.cpp @@ -20,14 +20,18 @@ #include -// Define parameters. -PROGRAM_INFO("Neighborhood Components Analysis (NCA)", - // Short description. +// Program Name. +BINDING_NAME("Neighborhood Components Analysis (NCA)"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of neighborhood components analysis, a distance learning" " technique that can be used for preprocessing. Given a labeled dataset, " "this uses NCA, which seeks to improve the k-nearest-neighbor " - "classification, and returns the learned distance metric.", - // Long description. + "classification, and returns the learned distance metric."); + +// Long description. +BINDING_LONG_DESC( "This program implements Neighborhood Components Analysis, both a linear " "dimensionality reduction technique and a distance learning technique. The" " method seeks to improve k-nearest-neighbor classification on a dataset " @@ -88,15 +92,17 @@ PROGRAM_INFO("Neighborhood Components Analysis (NCA)", "mlpack L-BFGS documentation (in lbfgs.hpp) or the vast set of published " "literature on L-BFGS." "\n\n" - "By default, the SGD optimizer is used.", - SEE_ALSO("@lmnn", "#lmnn"), - SEE_ALSO("Neighbourhood components analysis on Wikipedia", - "https://en.wikipedia.org/wiki/Neighbourhood_components_analysis"), - SEE_ALSO("Neighbourhood components analysis (pdf)", + "By default, the SGD optimizer is used."); + +// See also... +BINDING_SEE_ALSO("@lmnn", "#lmnn"); +BINDING_SEE_ALSO("Neighbourhood components analysis on Wikipedia", + "https://en.wikipedia.org/wiki/Neighbourhood_components_analysis"); +BINDING_SEE_ALSO("Neighbourhood components analysis (pdf)", "http://papers.nips.cc/paper/2566-neighbourhood-components-" - "analysis.pdf"), - SEE_ALSO("mlpack::nca::NCA C++ class documentation", - "@doxygen/classmlpack_1_1nca_1_1NCA.html")); + "analysis.pdf"); +BINDING_SEE_ALSO("mlpack::nca::NCA C++ class documentation", + "@doxygen/classmlpack_1_1nca_1_1NCA.html"); PARAM_MATRIX_IN_REQ("input", "Input dataset to run NCA on.", "i"); PARAM_MATRIX_OUT("output", "Output matrix for learned distance matrix.", "o"); diff --git a/src/mlpack/methods/neighbor_search/kfn_main.cpp b/src/mlpack/methods/neighbor_search/kfn_main.cpp index c152eb10a2..73b9dbd64f 100644 --- a/src/mlpack/methods/neighbor_search/kfn_main.cpp +++ b/src/mlpack/methods/neighbor_search/kfn_main.cpp @@ -32,19 +32,25 @@ using namespace mlpack::util; // Convenience typedef. typedef NSModel KFNModel; -// Information about the program itself. -PROGRAM_INFO("k-Furthest-Neighbors Search", - // Short description. +// Program Name. +BINDING_NAME("k-Furthest-Neighbors Search"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of k-furthest-neighbor search using single-tree and " "dual-tree algorithms. Given a set of reference points and query points, " "this can find the k furthest neighbors in the reference set of each query" - " point using trees; trees that are built can be saved for future use.", - // Long description. + " point using trees; trees that are built can be saved for future use."); + +// Long description. +BINDING_LONG_DESC( "This program will calculate the k-furthest-neighbors of a set of " "points. You may specify a separate set of reference points and query " "points, or just a reference set which will be used as both the reference " - "and query set." - "\n\n" + "and query set."); + +// Example. +BINDING_EXAMPLE( "For example, the following will calculate the 5 furthest neighbors of each" "point in " + PRINT_DATASET("input") + " and store the distances in " + PRINT_DATASET("distances") + " and the neighbors in " + @@ -57,13 +63,15 @@ PROGRAM_INFO("k-Furthest-Neighbors Search", "neighbors output matrix corresponds to the index of the point in the " "reference set which is the j'th furthest neighbor from the point in the " "query set with index i. Row i and column j in the distances output file " - "corresponds to the distance between those two points.", - SEE_ALSO("@approx_kfn", "#approx_kfn"), - SEE_ALSO("@knn", "#knn"), - SEE_ALSO("Tree-independent dual-tree algorithms (pdf)", - "http://proceedings.mlr.press/v28/curtin13.pdf"), - SEE_ALSO("mlpack::neighbor::NeighborSearch C++ class documentation", - "@doxygen/classmlpack_1_1neighbor_1_1NeighborSearch.html")); + "corresponds to the distance between those two points."); + +// See also... +BINDING_SEE_ALSO("@approx_kfn", "#approx_kfn"); +BINDING_SEE_ALSO("@knn", "#knn"); +BINDING_SEE_ALSO("Tree-independent dual-tree algorithms (pdf)", + "http://proceedings.mlr.press/v28/curtin13.pdf"); +BINDING_SEE_ALSO("mlpack::neighbor::NeighborSearch C++ class documentation", + "@doxygen/classmlpack_1_1neighbor_1_1NeighborSearch.html"); // Define our input parameters that this program will take. PARAM_MATRIX_IN("reference", "Matrix containing the reference dataset.", "r"); diff --git a/src/mlpack/methods/neighbor_search/knn_main.cpp b/src/mlpack/methods/neighbor_search/knn_main.cpp index e184469732..9f643ecd61 100644 --- a/src/mlpack/methods/neighbor_search/knn_main.cpp +++ b/src/mlpack/methods/neighbor_search/knn_main.cpp @@ -34,20 +34,26 @@ using namespace mlpack::util; // Convenience typedef. typedef NSModel KNNModel; -// Information about the program itself. -PROGRAM_INFO("k-Nearest-Neighbors Search", - // Short description. +// Program Name. +BINDING_NAME("k-Nearest-Neighbors Search"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of k-nearest-neighbor search using single-tree and " "dual-tree algorithms. Given a set of reference points and query points, " "this can find the k nearest neighbors in the reference set of each query " - "point using trees; trees that are built can be saved for future use.", - // Long description. + "point using trees; trees that are built can be saved for future use."); + +// Long description. +BINDING_LONG_DESC( "This program will calculate the k-nearest-neighbors of a set of " "points using kd-trees or cover trees (cover tree support is experimental " "and may be slow). You may specify a separate set of " "reference points and query points, or just a reference set which will be " - "used as both the reference and query set." - "\n\n" + "used as both the reference and query set."); + +// Example. +BINDING_EXAMPLE( "For example, the following command will calculate the 5 nearest neighbors " "of each point in " + PRINT_DATASET("input") + " and store the distances " "in " + PRINT_DATASET("distances") + " and the neighbors in " + @@ -60,16 +66,18 @@ PROGRAM_INFO("k-Nearest-Neighbors Search", "output matrix corresponds to the index of the point in the reference set " "which is the j'th nearest neighbor from the point in the query set with " "index i. Row j and column i in the distances output matrix corresponds to" - " the distance between those two points.", - SEE_ALSO("@lsh", "#lsh"), - SEE_ALSO("@krann", "#krann"), - SEE_ALSO("@kfn", "#kfn"), - SEE_ALSO("NeighborSearch tutorial (k-nearest-neighbors)", - "@doxygen/nstutorial.html"), - SEE_ALSO("Tree-independent dual-tree algorithms (pdf)", - "http://proceedings.mlr.press/v28/curtin13.pdf"), - SEE_ALSO("mlpack::neighbor::NeighborSearch C++ class documentation", - "@doxygen/classmlpack_1_1neighbor_1_1NeighborSearch.html")); + " the distance between those two points."); + +// See also... +BINDING_SEE_ALSO("@lsh", "#lsh"); +BINDING_SEE_ALSO("@krann", "#krann"); +BINDING_SEE_ALSO("@kfn", "#kfn"); +BINDING_SEE_ALSO("NeighborSearch tutorial (k-nearest-neighbors)", + "@doxygen/nstutorial.html"); +BINDING_SEE_ALSO("Tree-independent dual-tree algorithms (pdf)", + "http://proceedings.mlr.press/v28/curtin13.pdf"); +BINDING_SEE_ALSO("mlpack::neighbor::NeighborSearch C++ class documentation", + "@doxygen/classmlpack_1_1neighbor_1_1NeighborSearch.html"); // Define our input parameters that this program will take. PARAM_MATRIX_IN("reference", "Matrix containing the reference dataset.", "r"); diff --git a/src/mlpack/methods/nmf/nmf_main.cpp b/src/mlpack/methods/nmf/nmf_main.cpp index d5548ae136..56066a673b 100644 --- a/src/mlpack/methods/nmf/nmf_main.cpp +++ b/src/mlpack/methods/nmf/nmf_main.cpp @@ -27,12 +27,16 @@ using namespace mlpack::amf; using namespace mlpack::util; using namespace std; -// Document program. -PROGRAM_INFO("Non-negative Matrix Factorization", - // Short description. +// Program Name. +BINDING_NAME("Non-negative Matrix Factorization"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of non-negative matrix factorization. This can be used " - "to decompose an input dataset into two low-rank non-negative components.", - // Long description. + "to decompose an input dataset into two low-rank non-negative components."); + +// Long description. +BINDING_LONG_DESC( "This program performs non-negative matrix factorization on the given " "dataset, storing the resulting decomposed matrices in the specified " "files. For an input dataset V, NMF decomposes V into two matrices W " @@ -57,25 +61,29 @@ PROGRAM_INFO("Non-negative Matrix Factorization", "The maximum number of iterations is specified with " + PRINT_PARAM_STRING("max_iterations") + ", and the minimum residue " "required for algorithm termination is specified with the " + - PRINT_PARAM_STRING("min_residue") + " parameter." - "\n\n" + PRINT_PARAM_STRING("min_residue") + " parameter."); + +// Example. +BINDING_EXAMPLE( "For example, to run NMF on the input matrix " + PRINT_DATASET("V") + " " "using the 'multdist' update rules with a rank-10 decomposition and " "storing the decomposed matrices into " + PRINT_DATASET("W") + " and " + PRINT_DATASET("H") + ", the following command could be used: " "\n\n" + PRINT_CALL("nmf", "input", "V", "w", "W", "h", "H", "rank", 10, - "update_rules", "multdist"), - SEE_ALSO("@cf", "#cf"), - SEE_ALSO("Alternating matrix factorization tutorial", - "@doxygen/amftutorial.html"), - SEE_ALSO("Non-negative matrix factorization on Wikipedia", - "https://en.wikipedia.org/wiki/Non-negative_matrix_factorization"), - SEE_ALSO("Algorithms for non-negative matrix factorization (pdf)", + "update_rules", "multdist")); + +// See also... +BINDING_SEE_ALSO("@cf", "#cf"); +BINDING_SEE_ALSO("Alternating matrix factorization tutorial", + "@doxygen/amftutorial.html"); +BINDING_SEE_ALSO("Non-negative matrix factorization on Wikipedia", + "https://en.wikipedia.org/wiki/Non-negative_matrix_factorization"); +BINDING_SEE_ALSO("Algorithms for non-negative matrix factorization (pdf)", "http://papers.nips.cc/paper/1861-algorithms-for-non-negative-matrix-" - "factorization.pdf"), - SEE_ALSO("mlpack::amf::AMF C++ class documentation", - "@doxygen/classmlpack_1_1amf_1_1AMF.html")); + "factorization.pdf"); +BINDING_SEE_ALSO("mlpack::amf::AMF C++ class documentation", + "@doxygen/classmlpack_1_1amf_1_1AMF.html"); // Parameters for program. PARAM_MATRIX_IN_REQ("input", "Input dataset to perform NMF on.", "i"); diff --git a/src/mlpack/methods/pca/pca_main.cpp b/src/mlpack/methods/pca/pca_main.cpp index 749b23d253..8f5e78d68f 100644 --- a/src/mlpack/methods/pca/pca_main.cpp +++ b/src/mlpack/methods/pca/pca_main.cpp @@ -25,14 +25,18 @@ using namespace mlpack::pca; using namespace mlpack::util; using namespace std; -// Document program. -PROGRAM_INFO("Principal Components Analysis", - // Short description. +// Program Name. +BINDING_NAME("Principal Components Analysis"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of several strategies for principal components analysis " "(PCA), a common preprocessing step. Given a dataset and a desired new " "dimensionality, this can reduce the dimensionality of the data using the " - "linear transformation determined by PCA.", - // Long description. + "linear transformation determined by PCA."); + +// Long description. +BINDING_LONG_DESC( "This program performs principal components analysis on the given dataset " "using the exact, randomized, randomized block Krylov, or QUIC SVD method. " "It will transform the data onto its principal components, optionally " @@ -50,19 +54,23 @@ PROGRAM_INFO("Principal Components Analysis", "Multiple different decomposition techniques can be used. The method to " "use can be specified with the " + PRINT_PARAM_STRING("decomposition_method") + " parameter, and it may take " - "the values 'exact', 'randomized', or 'quic'." - "\n\n" + "the values 'exact', 'randomized', or 'quic'."); + +// Example. +BINDING_EXAMPLE( "For example, to reduce the dimensionality of the matrix " + PRINT_DATASET("data") + " to 5 dimensions using randomized SVD for the " "decomposition, storing the output matrix to " + PRINT_DATASET("data_mod") + ", the following command can be used:" "\n\n" + PRINT_CALL("pca", "input", "data", "new_dimensionality", 5, - "decomposition_method", "randomized", "output", "data_mod"), - SEE_ALSO("Principal component analysis on Wikipedia", - "https://en.wikipedia.org/wiki/Principal_component_analysis"), - SEE_ALSO("mlpack::pca::PCA C++ class documentation", - "@doxygen/classmlpack_1_1pca_1_1PCA.html")); + "decomposition_method", "randomized", "output", "data_mod")); + +// See also... +BINDING_SEE_ALSO("Principal component analysis on Wikipedia", + "https://en.wikipedia.org/wiki/Principal_component_analysis"); +BINDING_SEE_ALSO("mlpack::pca::PCA C++ class documentation", + "@doxygen/classmlpack_1_1pca_1_1PCA.html"); // Parameters for program. PARAM_MATRIX_IN_REQ("input", "Input dataset to perform PCA on.", "i"); diff --git a/src/mlpack/methods/perceptron/perceptron_main.cpp b/src/mlpack/methods/perceptron/perceptron_main.cpp index fa90b8b2c5..95649c6a12 100644 --- a/src/mlpack/methods/perceptron/perceptron_main.cpp +++ b/src/mlpack/methods/perceptron/perceptron_main.cpp @@ -25,13 +25,18 @@ using namespace mlpack::util; using namespace std; using namespace arma; -PROGRAM_INFO("Perceptron", - // Short description. +// Program Name. +BINDING_NAME("Perceptron"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of a perceptron---a single level neural network--=for " "classification. Given labeled data, a perceptron can be trained and saved" " for future use; or, a pre-trained perceptron can be used for " - "classification on new points.", - // Long description. + "classification on new points."); + +// Long description. +BINDING_LONG_DESC( "This program implements a perceptron, which is a single level neural " "network. The perceptron makes its predictions based on a linear predictor " "function combining a set of weights with the feature vector. The " @@ -63,8 +68,10 @@ PROGRAM_INFO("Perceptron", " option may have class labels as its last dimension (so, if the training " "data is in CSV format, labels should be the last column). Alternately, " "the " + PRINT_PARAM_STRING("labels") + " parameter may be used to specify " - "a separate matrix of labels." - "\n\n" + "a separate matrix of labels."); + +// Example. +BINDING_EXAMPLE( "All these options make it easy to train a perceptron, and then re-use that" " perceptron for later classification. The invocation below trains a " "perceptron on " + PRINT_DATASET("training_data") + " with labels " + @@ -89,12 +96,14 @@ PROGRAM_INFO("Perceptron", "cannot pass a perceptron model trained on 2 classes and then re-train with" " a 4-class dataset. Similarly, attempting classification on a " "3-dimensional dataset with a perceptron that has been trained on 8 " - "dimensions will cause an error.", - SEE_ALSO("@adaboost", "#adaboost"), - SEE_ALSO("Perceptron on Wikipedia", - "https://en.wikipedia.org/wiki/Perceptron"), - SEE_ALSO("mlpack::perceptron::Perceptron C++ class documentation", - "@doxygen/classmlpack_1_1perceptron_1_1Perceptron.html")); + "dimensions will cause an error."); + +// See also... +BINDING_SEE_ALSO("@adaboost", "#adaboost"); +BINDING_SEE_ALSO("Perceptron on Wikipedia", + "https://en.wikipedia.org/wiki/Perceptron"); +BINDING_SEE_ALSO("mlpack::perceptron::Perceptron C++ class documentation", + "@doxygen/classmlpack_1_1perceptron_1_1Perceptron.html"); // When we save a model, we must also save the class mappings. So we use this // auxiliary structure to store both the perceptron and the mapping, and we'll diff --git a/src/mlpack/methods/preprocess/image_converter_main.cpp b/src/mlpack/methods/preprocess/image_converter_main.cpp index cdb9b3c1bb..22bc727a59 100644 --- a/src/mlpack/methods/preprocess/image_converter_main.cpp +++ b/src/mlpack/methods/preprocess/image_converter_main.cpp @@ -20,13 +20,18 @@ using namespace arma; using namespace std; using namespace mlpack::data; -PROGRAM_INFO("Image Converter", - // Short description. +// Program Name. +BINDING_NAME("Image Converter"); + +// Short description. +BINDING_SHORT_DESC( "A utility to load an image or set of images into a single dataset that" " can then be used by other mlpack methods and utilities. This can also" " unpack an image dataset into individual files, for instance after mlpack" - " methods have been used.", - // Long description. + " methods have been used."); + +// Long description. +BINDING_LONG_DESC( "This utility takes an image or an array of images and loads them to a" " matrix. You can optionally specify the height " + PRINT_PARAM_STRING("height") + " width " + PRINT_PARAM_STRING("width") @@ -39,18 +44,24 @@ PROGRAM_INFO("Image Converter", + ".\n\n" + "You can also provide a dataset and save them as images using " + PRINT_PARAM_STRING("dataset") + " and " + PRINT_PARAM_STRING("save") + - " as an parameter. An example to load an image : " + + " as an parameter."); + +// Example. +BINDING_EXAMPLE( + " An example to load an image : " "\n\n" + PRINT_CALL("image_converter", "input", "X", "height", 256, "width", 256, "channels", 3, "output", "Y") + "\n\n" + - " An example to save an image is :" + + " An example to save an image is :" "\n\n" + PRINT_CALL("image_converter", "input", "X", "height", 256, "width", 256, - "channels", 3, "dataset", "Y", "save", true), - SEE_ALSO("@preprocess_binarize", "#preprocess_binarize"), - SEE_ALSO("@preprocess_describe", "#preprocess_describe"), - SEE_ALSO("@preprocess_imputer", "#preprocess_imputer")); + "channels", 3, "dataset", "Y", "save", true)); + +// See also... +BINDING_SEE_ALSO("@preprocess_binarize", "#preprocess_binarize"); +BINDING_SEE_ALSO("@preprocess_describe", "#preprocess_describe"); +BINDING_SEE_ALSO("@preprocess_imputer", "#preprocess_imputer"); // DEFINE PARAM PARAM_VECTOR_IN_REQ(string, "input", "Image filenames which have to " diff --git a/src/mlpack/methods/preprocess/preprocess_binarize_main.cpp b/src/mlpack/methods/preprocess/preprocess_binarize_main.cpp index 321399c76e..f47e623e27 100644 --- a/src/mlpack/methods/preprocess/preprocess_binarize_main.cpp +++ b/src/mlpack/methods/preprocess/preprocess_binarize_main.cpp @@ -14,12 +14,17 @@ #include #include -PROGRAM_INFO("Binarize Data", - // Short description. +// Program Name. +BINDING_NAME("Binarize Data"); + +// Short description. +BINDING_SHORT_DESC( "A utility to binarize a dataset. Given a dataset, this utility converts " "each value in the desired dimension(s) to 0 or 1; this can be a useful " - "preprocessing step.", - // Long description. + "preprocessing step."); + +// Long description. +BINDING_LONG_DESC( "This utility takes a dataset and binarizes the " "variables into either 0 or 1 given threshold. User can apply binarization " "on a dimension or the whole dataset. The dimension to apply binarization " @@ -30,8 +35,10 @@ PROGRAM_INFO("Binarize Data", "0.0." "\n\n" "The binarized matrix may be saved with the " + - PRINT_PARAM_STRING("output") + " output parameter." - "\n\n" + PRINT_PARAM_STRING("output") + " output parameter."); + +// Example. +BINDING_EXAMPLE( "For example, if we want to set all variables greater than 5 in the " "dataset " + PRINT_DATASET("X") + " to 1 and variables less than or equal " "to 5.0 to 0, and save the result to " + PRINT_DATASET("Y") + ", we could " @@ -44,10 +51,12 @@ PROGRAM_INFO("Binarize Data", PRINT_DATASET("X") + ", we could instead run" "\n\n" + PRINT_CALL("preprocess_binarize", "input", "X", "threshold", 5.0, - "dimension", 0, "output", "Y"), - SEE_ALSO("@preprocess_describe", "#preprocess_describe"), - SEE_ALSO("@preprocess_imputer", "#preprocess_imputer"), - SEE_ALSO("@preprocess_split", "#preprocess_split")); + "dimension", 0, "output", "Y")); + +// See also... +BINDING_SEE_ALSO("@preprocess_describe", "#preprocess_describe"); +BINDING_SEE_ALSO("@preprocess_imputer", "#preprocess_imputer"); +BINDING_SEE_ALSO("@preprocess_split", "#preprocess_split"); // Define parameters for data. PARAM_MATRIX_IN_REQ("input", "Input data matrix.", "i"); diff --git a/src/mlpack/methods/preprocess/preprocess_describe_main.cpp b/src/mlpack/methods/preprocess/preprocess_describe_main.cpp index acb9f9002c..316cdd2ef9 100644 --- a/src/mlpack/methods/preprocess/preprocess_describe_main.cpp +++ b/src/mlpack/methods/preprocess/preprocess_describe_main.cpp @@ -22,11 +22,16 @@ using namespace mlpack::util; using namespace std; using namespace boost; -PROGRAM_INFO("Descriptive Statistics", - // Short description. +// Program Name. +BINDING_NAME("Descriptive Statistics"); + +// Short description. +BINDING_SHORT_DESC( "A utility for printing descriptive statistics about a dataset. This " - "prints a number of details about a dataset in a tabular format.", - // Long description. + "prints a number of details about a dataset in a tabular format."); + +// Long description. +BINDING_LONG_DESC( "This utility takes a dataset and prints out the descriptive statistics " "of the data. Descriptive statistics is the discipline of quantitatively " "describing the main features of a collection of information, or the " @@ -40,8 +45,10 @@ PROGRAM_INFO("Descriptive Statistics", "specific dimension to analyze if there are too many dimensions. The " + PRINT_PARAM_STRING("population") + " parameter can be specified when the " "dataset should be considered as a population. Otherwise, the dataset " - "will be considered as a sample." - "\n\n" + "will be considered as a sample."); + +// Example. +BINDING_EXAMPLE( "So, a simple example where we want to print out statistical facts about " "the dataset " + PRINT_DATASET("X") + " using the default settings, we " "could run " @@ -52,10 +59,12 @@ PROGRAM_INFO("Descriptive Statistics", "the dataset as a population, we could run" "\n\n" + PRINT_CALL("preprocess_describe", "input", "X", "width", 10, "precision", 5, - "verbose", true), - SEE_ALSO("@preprocess_binarize", "#preprocess_binarize"), - SEE_ALSO("@preprocess_imputer", "#preprocess_imputer"), - SEE_ALSO("@preprocess_split", "#preprocess_split")); + "verbose", true)); + +// See also... +BINDING_SEE_ALSO("@preprocess_binarize", "#preprocess_binarize"); +BINDING_SEE_ALSO("@preprocess_imputer", "#preprocess_imputer"); +BINDING_SEE_ALSO("@preprocess_split", "#preprocess_split"); // Define parameters for data. PARAM_MATRIX_IN_REQ("input", "Matrix containing data,", "i"); diff --git a/src/mlpack/methods/preprocess/preprocess_imputer_main.cpp b/src/mlpack/methods/preprocess/preprocess_imputer_main.cpp index 85189d68f6..236b339832 100644 --- a/src/mlpack/methods/preprocess/preprocess_imputer_main.cpp +++ b/src/mlpack/methods/preprocess/preprocess_imputer_main.cpp @@ -22,28 +22,38 @@ #include #include -PROGRAM_INFO("Impute Data", - // Short description. +// Program Name. +BINDING_NAME("Impute Data"); + +// Short description. +BINDING_SHORT_DESC( "This utility provides several imputation strategies for missing data. " "Given a dataset with missing values, this can impute according to several " - "strategies, including user-defined values.", - // Long description. + "strategies, including user-defined values."); + +// Long description. +BINDING_LONG_DESC( "This utility takes a dataset and converts a user-defined missing variable " "to another to provide more meaningful analysis." "\n\n" "The program does not modify the original file, but instead makes a " "separate file to save the output data; You can save the output by " "specifying the file name with --output_file (-o)." - "\n\n" + "\n\n"); + +// Example. +BINDING_EXAMPLE( "For example, if we consider 'NULL' in dimension 0 to be a missing " "variable and want to delete whole row containing the NULL in the " "column-wise dataset, and save the result to result.csv, we could run" "\n\n" "$ mlpack_preprocess_imputer -i dataset.csv -o result.csv -m NULL -d 0 \n" - "> -s listwise_deletion", - SEE_ALSO("@preprocess_binarize", "#preprocess_binarize"), - SEE_ALSO("@preprocess_describe", "#preprocess_describe"), - SEE_ALSO("@preprocess_split", "#preprocess_split")); + "> -s listwise_deletion"); + +// See also... +BINDING_SEE_ALSO("@preprocess_binarize", "#preprocess_binarize"); +BINDING_SEE_ALSO("@preprocess_describe", "#preprocess_describe"); +BINDING_SEE_ALSO("@preprocess_split", "#preprocess_split"); PARAM_STRING_IN_REQ("input_file", "File containing data.", "i"); PARAM_STRING_OUT("output_file", "File to save output into.", "o"); diff --git a/src/mlpack/methods/preprocess/preprocess_scale_main.cpp b/src/mlpack/methods/preprocess/preprocess_scale_main.cpp index dfcecc9ad2..1c4759f0a9 100644 --- a/src/mlpack/methods/preprocess/preprocess_scale_main.cpp +++ b/src/mlpack/methods/preprocess/preprocess_scale_main.cpp @@ -28,12 +28,17 @@ using namespace mlpack::data; using namespace arma; using namespace std; -PROGRAM_INFO("Scale Data", - // Short description. +// Program Name. +BINDING_NAME("Scale Data"); + +// Short description. +BINDING_SHORT_DESC( "A utility to perform feature scaling on datasets using one of six" "techniques. Both scaling and inverse scaling are supported, and" - "scalers can be saved and then applied to other datasets.", - // Long description. + "scalers can be saved and then applied to other datasets."); + +// Long description. +BINDING_LONG_DESC( "This utility takes a dataset and performs feature scaling using one of " "the six scaler methods namely: 'max_abs_scaler', 'mean_normalization', " "'min_max_scaler' ,'standard_scaler', 'pca_whitening' and 'zca_whitening'." @@ -47,8 +52,10 @@ PROGRAM_INFO("Scale Data", "\n\n" "The model to scale features can be saved using " + PRINT_PARAM_STRING("output_model") + " and later can be loaded back using" - + PRINT_PARAM_STRING("input_model") + "." - "\n\n" + + PRINT_PARAM_STRING("input_model") + "."); + +// Example. +BINDING_EXAMPLE( "So, a simple example where we want to scale the dataset " + PRINT_DATASET("X") + " into " + PRINT_DATASET("X_scaled")+ " with " " standard_scaler as scaler_method, we could run " @@ -78,10 +85,12 @@ PROGRAM_INFO("Scale Data", " of default 0 to 1. We could run " "\n\n" + PRINT_CALL("preprocess_scale", "input", "X", "output", "X_scaled", - "scaler_method", "min_max_scaler", "min_value", 1, "max_value", 3), - SEE_ALSO("@preprocess_binarize", "#preprocess_binarize"), - SEE_ALSO("@preprocess_describe", "#preprocess_describe"), - SEE_ALSO("@preprocess_imputer", "#preprocess_imputer")); + "scaler_method", "min_max_scaler", "min_value", 1, "max_value", 3)); + +// See also... +BINDING_SEE_ALSO("@preprocess_binarize", "#preprocess_binarize"); +BINDING_SEE_ALSO("@preprocess_describe", "#preprocess_describe"); +BINDING_SEE_ALSO("@preprocess_imputer", "#preprocess_imputer"); // Define parameters for data. PARAM_MATRIX_IN_REQ("input", "Matrix containing data.", "i"); diff --git a/src/mlpack/methods/preprocess/preprocess_split_main.cpp b/src/mlpack/methods/preprocess/preprocess_split_main.cpp index 401a55d855..b6a36967a1 100644 --- a/src/mlpack/methods/preprocess/preprocess_split_main.cpp +++ b/src/mlpack/methods/preprocess/preprocess_split_main.cpp @@ -15,11 +15,16 @@ #include #include -PROGRAM_INFO("Split Data", - // Short description. +// Program Name. +BINDING_NAME("Split Data"); + +// Short description. +BINDING_SHORT_DESC( "A utility to split data into a training and testing dataset. This can " - "also split labels according to the same split.", - // Long description. + "also split labels according to the same split."); + +// Long description. +BINDING_LONG_DESC( "This utility takes a dataset and optionally labels and splits them into a " "training set and a test set. Before the split, the points in the dataset " "are randomly reordered. The percentage of the dataset to be used as the " @@ -35,8 +40,10 @@ PROGRAM_INFO("Split Data", "labels works the same way as splitting the data. The output training and " "test labels may be saved with the " + PRINT_PARAM_STRING("training_labels") + " and " + - PRINT_PARAM_STRING("test_labels") + " output parameters, respectively." - "\n\n" + PRINT_PARAM_STRING("test_labels") + " output parameters, respectively."); + +// Example. +BINDING_EXAMPLE( "So, a simple example where we want to split the dataset " + PRINT_DATASET("X") + " into " + PRINT_DATASET("X_train") + " and " + PRINT_DATASET("X_test") + " with 60% of the data in the training set and " @@ -60,10 +67,12 @@ PROGRAM_INFO("Split Data", "\n\n" + PRINT_CALL("preprocess_split", "input", "X", "input_labels", "y", "test_ratio", 0.3, "training", "X_train", "training_labels", "y_train", - "test", "X_test", "test_labels", "y_test"), - SEE_ALSO("@preprocess_binarize", "#preprocess_binarize"), - SEE_ALSO("@preprocess_describe", "#preprocess_describe"), - SEE_ALSO("@preprocess_imputer", "#preprocess_imputer")); + "test", "X_test", "test_labels", "y_test")); + +// See also... +BINDING_SEE_ALSO("@preprocess_binarize", "#preprocess_binarize"); +BINDING_SEE_ALSO("@preprocess_describe", "#preprocess_describe"); +BINDING_SEE_ALSO("@preprocess_imputer", "#preprocess_imputer"); // Define parameters for data. PARAM_MATRIX_IN_REQ("input", "Matrix containing data.", "i"); diff --git a/src/mlpack/methods/radical/radical_main.cpp b/src/mlpack/methods/radical/radical_main.cpp index f474433b58..1d520d2bcb 100644 --- a/src/mlpack/methods/radical/radical_main.cpp +++ b/src/mlpack/methods/radical/radical_main.cpp @@ -16,13 +16,18 @@ #include #include "radical.hpp" -PROGRAM_INFO("RADICAL", - // Short description. +// Program Name. +BINDING_NAME("RADICAL"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of RADICAL, a method for independent component analysis " "(ICA). Given a dataset, this can decompose the dataset into an unmixing " "matrix and an independent component matrix; this can be useful for " - "preprocessing.", - // Long description. + "preprocessing."); + +// Long description. +BINDING_LONG_DESC( "An implementation of RADICAL, a method for independent component analysis " "(ICA). Assuming that we have an input matrix X, the goal is to find a " "square unmixing matrix W such that Y = W * X and the dimensions of Y are " @@ -33,20 +38,24 @@ PROGRAM_INFO("RADICAL", PRINT_PARAM_STRING("input") + " parameter. The output matrix Y may be " "saved with the " + PRINT_PARAM_STRING("output_ic") + " output parameter, " "and the output unmixing matrix W may be saved with the " + - PRINT_PARAM_STRING("output_unmixing") + " output parameter." - "\n\n" + PRINT_PARAM_STRING("output_unmixing") + " output parameter."); + +// Example. +BINDING_EXAMPLE( "For example, to perform ICA on the matrix " + PRINT_DATASET("X") + " with " "40 replicates, saving the independent components to " + PRINT_DATASET("ic") + ", the following command may be used: " "\n\n" + - PRINT_CALL("radical", "input", "X", "replicates", 40, "output_ic", "ic"), - SEE_ALSO("Independent component analysis on Wikipedia", - "https://en.wikipedia.org/wiki/Independent_component_analysis"), - SEE_ALSO("ICA using spacings estimates of entropy (pdf)", + PRINT_CALL("radical", "input", "X", "replicates", 40, "output_ic", "ic")); + +// See also... +BINDING_SEE_ALSO("Independent component analysis on Wikipedia", + "https://en.wikipedia.org/wiki/Independent_component_analysis"); +BINDING_SEE_ALSO("ICA using spacings estimates of entropy (pdf)", "http://www.jmlr.org/papers/volume4/learned-miller03a/" - "learned-miller03a.pdf"), - SEE_ALSO("mlpack::radical::Radical C++ class documentation", - "@doxygen/classmlpack_1_1radical_1_1Radical.html")); + "learned-miller03a.pdf"); +BINDING_SEE_ALSO("mlpack::radical::Radical C++ class documentation", + "@doxygen/classmlpack_1_1radical_1_1Radical.html"); PARAM_MATRIX_IN_REQ("input", "Input dataset for ICA.", "i"); diff --git a/src/mlpack/methods/random_forest/random_forest_main.cpp b/src/mlpack/methods/random_forest/random_forest_main.cpp index 1d599805e9..ade8957c81 100644 --- a/src/mlpack/methods/random_forest/random_forest_main.cpp +++ b/src/mlpack/methods/random_forest/random_forest_main.cpp @@ -19,13 +19,18 @@ using namespace mlpack::tree; using namespace mlpack::util; using namespace std; -PROGRAM_INFO("Random forests", - // Short description. +// Program Name. +BINDING_NAME("Random forests"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of the standard random forest algorithm by Leo Breiman " "for classification. Given labeled data, a random forest can be trained " "and saved for future use; or, a pre-trained random forest can be used for " - "classification.", - // Long description. + "classification."); + +// Long description. +BINDING_LONG_DESC( "This program is an implementation of the standard random forest " "classification algorithm by Leo Breiman. A random forest can be " "trained and saved for later use, or a random forest may be loaded " @@ -64,8 +69,10 @@ PROGRAM_INFO("Random forests", PRINT_PARAM_STRING("test_labels") + " parameter. Predictions for each " "test point may be saved via the " + PRINT_PARAM_STRING("predictions") + "output parameter. Class probabilities for each prediction may be saved " - "with the " + PRINT_PARAM_STRING("probabilities") + " output parameter." - "\n\n" + "with the " + PRINT_PARAM_STRING("probabilities") + " output parameter."); + +// Example. +BINDING_EXAMPLE( "For example, to train a random forest with a minimum leaf size of 20 " "using 10 trees on the dataset contained in " + PRINT_DATASET("data") + "with labels " + PRINT_DATASET("labels") + ", saving the output random " @@ -83,16 +90,18 @@ PROGRAM_INFO("Random forests", "could call " "\n\n" + PRINT_CALL("random_forest", "input_model", "rf_model", "test", "test_set", - "test_labels", "test_labels", "predictions", "predictions"), - SEE_ALSO("@decision_tree", "#decision_tree"), - SEE_ALSO("@hoeffding_tree", "#hoeffding_tree"), - SEE_ALSO("@softmax_regression", "#softmax_regression"), - SEE_ALSO("Random forest on Wikipedia", - "https://en.wikipedia.org/wiki/Random_forest"), - SEE_ALSO("Random forests (pdf)", - "https://link.springer.com/content/pdf/10.1023/A:1010933404324.pdf"), - SEE_ALSO("mlpack::tree::RandomForest C++ class documentation", - "@doxygen/classmlpack_1_1tree_1_1RandomForest.html")); + "test_labels", "test_labels", "predictions", "predictions")); + +// See also... +BINDING_SEE_ALSO("@decision_tree", "#decision_tree"); +BINDING_SEE_ALSO("@hoeffding_tree", "#hoeffding_tree"); +BINDING_SEE_ALSO("@softmax_regression", "#softmax_regression"); +BINDING_SEE_ALSO("Random forest on Wikipedia", + "https://en.wikipedia.org/wiki/Random_forest"); +BINDING_SEE_ALSO("Random forests (pdf)", + "https://link.springer.com/content/pdf/10.1023/A:1010933404324.pdf"); +BINDING_SEE_ALSO("mlpack::tree::RandomForest C++ class documentation", + "@doxygen/classmlpack_1_1tree_1_1RandomForest.html"); PARAM_MATRIX_IN("training", "Training dataset.", "t"); PARAM_UROW_IN("labels", "Labels for training dataset.", "l"); diff --git a/src/mlpack/methods/range_search/range_search_main.cpp b/src/mlpack/methods/range_search/range_search_main.cpp index e171341e1b..3dfb87155f 100644 --- a/src/mlpack/methods/range_search/range_search_main.cpp +++ b/src/mlpack/methods/range_search/range_search_main.cpp @@ -27,15 +27,19 @@ using namespace mlpack::tree; using namespace mlpack::metric; using namespace mlpack::util; -// Information about the program itself. -PROGRAM_INFO("Range Search", - // Short description. +// Program Name. +BINDING_NAME("Range Search"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of range search with single-tree and dual-tree " "algorithms. Given a set of reference points and a set of query points and" " a range, this can find the set of reference points within the desired " "range for each query point, and any trees built during the computation can" - " be saved for reuse with future range searches.", - // Long description. + " be saved for reuse with future range searches."); + +// Long description. +BINDING_LONG_DESC( "This program implements range search with a Euclidean distance metric. " "For a given query point, a given range, and a given set of reference " "points, the program will return all of the reference points with distance " @@ -44,8 +48,10 @@ PROGRAM_INFO("Range Search", " points, or only a reference set -- which is then used as both the " "reference and query set. The given range is taken to be inclusive (that " "is, points with a distance exactly equal to the minimum and maximum of the" - " range are included in the results)." - "\n\n" + " range are included in the results)."); + +// Example. +BINDING_EXAMPLE( "For example, the following will calculate the points within the range [2, " "5] of each point in 'input.csv' and store the distances in 'distances.csv'" " and the neighbors in 'neighbors.csv':" @@ -62,14 +68,16 @@ PROGRAM_INFO("Range Search", " resultant CSV-like files may not be loadable by many programs. However, " "at this time a better way to store this non-square result is not known. " "As a result, any output files will be written as CSVs in this manner, " - "regardless of the given extension.", - SEE_ALSO("@knn", "#knn"), - SEE_ALSO("Range searching on Wikipedia", - "https://en.wikipedia.org/wiki/Range_searching"), - SEE_ALSO("Tree-independent dual-tree algorithms (pdf)", - "http://proceedings.mlr.press/v28/curtin13.pdf"), - SEE_ALSO("mlpack::range::RangeSearch C++ class documentation", - "@doxygen/classmlpack_1_1range_1_1RangeSearch.html")); + "regardless of the given extension."); + +// See also... +BINDING_SEE_ALSO("@knn", "#knn"); +BINDING_SEE_ALSO("Range searching on Wikipedia", + "https://en.wikipedia.org/wiki/Range_searching"); +BINDING_SEE_ALSO("Tree-independent dual-tree algorithms (pdf)", + "http://proceedings.mlr.press/v28/curtin13.pdf"); +BINDING_SEE_ALSO("mlpack::range::RangeSearch C++ class documentation", + "@doxygen/classmlpack_1_1range_1_1RangeSearch.html"); // Define our input parameters that this program will take. PARAM_MATRIX_IN("reference", "Matrix containing the reference dataset.", "r"); diff --git a/src/mlpack/methods/rann/krann_main.cpp b/src/mlpack/methods/rann/krann_main.cpp index 69f403c4d9..9d830f5fff 100644 --- a/src/mlpack/methods/rann/krann_main.cpp +++ b/src/mlpack/methods/rann/krann_main.cpp @@ -28,21 +28,27 @@ using namespace mlpack::util; // Convenience typedef. typedef RAModel RANNModel; -// Information about the program itself. -PROGRAM_INFO("K-Rank-Approximate-Nearest-Neighbors (kRANN)", - // Short description. +// Program Name. +BINDING_NAME("K-Rank-Approximate-Nearest-Neighbors (kRANN)"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of rank-approximate k-nearest-neighbor search (kRANN) " " using single-tree and dual-tree algorithms. Given a set of reference " "points and query points, this can find the k nearest neighbors in the " "reference set of each query point using trees; trees that are built can " - "be saved for future use.", - // Long description. + "be saved for future use."); + +// Long description. +BINDING_LONG_DESC( "This program will calculate the k rank-approximate-nearest-neighbors of a " "set of points. You may specify a separate set of reference points and " "query points, or just a reference set which will be used as both the " "reference and query set. You must specify the rank approximation (in %) " - "(and optionally the success probability)." - "\n\n" + "(and optionally the success probability)."); + +// Example. +BINDING_EXAMPLE( "For example, the following will return 5 neighbors from the top 0.1% of " "the data (with probability 0.95) for each point in " + PRINT_DATASET("input") + " and store the distances in " + @@ -62,15 +68,17 @@ PROGRAM_INFO("K-Rank-Approximate-Nearest-Neighbors (kRANN)", "neighbors output file corresponds to the index of the point in the " "reference set which is the i'th nearest neighbor from the point in the " "query set with index j. Row i and column j in the distances output file " - "corresponds to the distance between those two points.", - SEE_ALSO("@knn", "#knn"), - SEE_ALSO("@lsh", "#lsh"), - SEE_ALSO("Rank-approximate nearest neighbor search: Retaining meaning and " - "speed in high dimensions (pdf)", "https://papers.nips.cc/paper/3864-" - "rank-approximate-nearest-neighbor-search-retaining-meaning-and-speed-" - "in-high-dimensions.pdf"), - SEE_ALSO("mlpack::neighbor::RASearch C++ class documentation", - "@doxygen/classmlpack_1_1neighbor_1_1RASearch.html")); + "corresponds to the distance between those two points."); + +// See also... +BINDING_SEE_ALSO("@knn", "#knn"); +BINDING_SEE_ALSO("@lsh", "#lsh"); +BINDING_SEE_ALSO("Rank-approximate nearest neighbor search: Retaining meaning" + " and speed in high dimensions (pdf)", "https://papers.nips.cc/paper/" + "3864-rank-approximate-nearest-neighbor-search-retaining-meaning-and" + "-speed-in-high-dimensions.pdf"); +BINDING_SEE_ALSO("mlpack::neighbor::RASearch C++ class documentation", + "@doxygen/classmlpack_1_1neighbor_1_1RASearch.html"); // Define our input parameters that this program will take. PARAM_MATRIX_IN("reference", "Matrix containing the reference dataset.", "r"); diff --git a/src/mlpack/methods/reinforcement_learning/environment/env_type.hpp b/src/mlpack/methods/reinforcement_learning/environment/env_type.hpp index e15093120a..e8513e3bb9 100644 --- a/src/mlpack/methods/reinforcement_learning/environment/env_type.hpp +++ b/src/mlpack/methods/reinforcement_learning/environment/env_type.hpp @@ -163,9 +163,15 @@ class ContinuousActionEnv class Action { public: - double action[1]; + std::vector action; // Storing degree of freedom. static size_t size; + + /** + * Construct an action instance. + */ + Action() : action(ContinuousActionEnv::Action::size) + { /* Nothing to do here */ } }; /** diff --git a/src/mlpack/methods/reinforcement_learning/environment/pendulum.hpp b/src/mlpack/methods/reinforcement_learning/environment/pendulum.hpp index 843cdf8557..cb810a33bc 100644 --- a/src/mlpack/methods/reinforcement_learning/environment/pendulum.hpp +++ b/src/mlpack/methods/reinforcement_learning/environment/pendulum.hpp @@ -95,7 +95,12 @@ class Pendulum class Action { public: - double action[1]; + /** + * Construct an action instance. + */ + Action() : action(1) + { /* Nothing to do here */ } + std::vector action; // Storing degree of freedom. static const size_t size = 1; }; diff --git a/src/mlpack/methods/reinforcement_learning/sac_impl.hpp b/src/mlpack/methods/reinforcement_learning/sac_impl.hpp index 5cad9ab285..cae78e95a2 100644 --- a/src/mlpack/methods/reinforcement_learning/sac_impl.hpp +++ b/src/mlpack/methods/reinforcement_learning/sac_impl.hpp @@ -62,10 +62,17 @@ SAC< targetQ2Network = learningQ2Network; // Reset all the networks. - learningQ1Network.ResetParameters(); + // Note: the q and policy networks have an if condition before reset. + // This is because we don't want to reset a loaded(possibly pretrained) model + // passed using this constructor. + if (learningQ1Network.Parameters().is_empty()) + { + learningQ1Network.ResetParameters(); + learningQ2Network.ResetParameters(); + } + if (policyNetwork.Parameters().is_empty()) + policyNetwork.ResetParameters(); targetQ1Network.ResetParameters(); - policyNetwork.ResetParameters(); - learningQ2Network.ResetParameters(); targetQ2Network.ResetParameters(); #if ENS_VERSION_MAJOR == 1 @@ -176,7 +183,8 @@ void SAC< arma::mat sampledActionValues(action.size, sampledActions.size()); for (size_t i = 0; i < sampledActions.size(); i++) - sampledActionValues.col(i) = sampledActions[i].action[0]; + sampledActionValues.col(i) = arma::conv_to::from + (sampledActions[i].action); arma::mat learningQInput = arma::join_vert(sampledActionValues, sampledStates); learningQ1Network.Forward(learningQInput, Q1); @@ -207,7 +215,7 @@ void SAC< // Actor network update. - arma::rowvec pi; + arma::mat pi; policyNetwork.Predict(sampledStates, pi); arma::mat qInput = arma::join_vert(pi, sampledStates); @@ -226,26 +234,26 @@ void SAC< arma::colvec singlePi; policyNetwork.Forward(singleState, singlePi); arma::colvec input = arma::join_vert(singlePi, singleState); - arma::rowvec weightLastLayer; + arma::mat weightLastLayer; if (Q1(i) < Q2(i)) { learningQ1Network.Forward(input, q); learningQ1Network.Backward(input, -1, gradQ); - weightLastLayer = learningQ1Network.Parameters(). - rows(0, hidden1 - 1).t(); + weightLastLayer = arma::reshape(learningQ1Network.Parameters(). + rows(0, hidden1 * singlePi.n_rows - 1), hidden1, singlePi.n_rows); } else { learningQ2Network.Forward(input, q); learningQ2Network.Backward(input, -1, gradQ); - weightLastLayer = learningQ2Network.Parameters(). - rows(0, hidden1 - 1).t(); + weightLastLayer = arma::reshape(learningQ2Network.Parameters(). + rows(0, hidden1 * singlePi.n_rows - 1), hidden1, singlePi.n_rows); } arma::colvec gradQBias = gradQ(input.n_rows * hidden1, 0, arma::size(hidden1, 1)); - arma::mat gradPolicy = weightLastLayer * gradQBias; + arma::mat gradPolicy = weightLastLayer.t() * gradQBias; policyNetwork.Backward(singleState, gradPolicy, grad); if (i == 0) { @@ -284,16 +292,16 @@ void SAC< >::SelectAction() { // Get the action at current state, from policy. - arma::rowvec outputAction; + arma::colvec outputAction; policyNetwork.Predict(state.Encode(), outputAction); if (!deterministic) { - arma::rowvec noise = arma::randn(outputAction.n_rows) * 0.1; + arma::colvec noise = arma::randn(outputAction.n_rows) * 0.1; noise = arma::clamp(noise, -0.25, 0.25); outputAction = outputAction + noise; } - action.action[0] = outputAction[0]; + action.action = arma::conv_to>::from(outputAction); } template < diff --git a/src/mlpack/methods/softmax_regression/softmax_regression_main.cpp b/src/mlpack/methods/softmax_regression/softmax_regression_main.cpp index 0344baf7aa..571b239187 100644 --- a/src/mlpack/methods/softmax_regression/softmax_regression_main.cpp +++ b/src/mlpack/methods/softmax_regression/softmax_regression_main.cpp @@ -23,15 +23,19 @@ using namespace mlpack; using namespace mlpack::regression; using namespace mlpack::util; -// Define parameters for the executable. -PROGRAM_INFO("Softmax Regression", - // Short description. +// Program Name. +BINDING_NAME("Softmax Regression"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of softmax regression for classification, which is a " "multiclass generalization of logistic regression. Given labeled data, a " "softmax regression model can be trained and saved for future use, or, a " "pre-trained softmax regression model can be used for classification of " - "new points.", - // Long description. + "new points."); + +// Long description. +BINDING_LONG_DESC( "This program performs softmax regression, a generalization of logistic " "regression to the multiclass case, and has support for L2 regularization. " " The program is able to train a model, load an existing model, and give " @@ -63,8 +67,10 @@ PROGRAM_INFO("Softmax Regression", "specified for the test data with the " + PRINT_PARAM_STRING("test_labels") + " parameter, then the program will " "print the accuracy of the predictions on the given test set and its " - "corresponding labels." - "\n\n" + "corresponding labels."); + +// Example. +BINDING_EXAMPLE( "For example, to train a softmax regression model on the data " + PRINT_DATASET("dataset") + " with labels " + PRINT_DATASET("labels") + " with a maximum of 1000 iterations for training, saving the trained model " @@ -78,14 +84,17 @@ PROGRAM_INFO("Softmax Regression", " " + PRINT_DATASET("predictions") + ", the following command can be used:" "\n\n" + PRINT_CALL("softmax_regression", "input_model", "sr_model", "test", - "test_points", "predictions", "predictions"), - SEE_ALSO("@logistic_regression", "#logistic_regression"), - SEE_ALSO("@random_forest", "#random_forest"), - SEE_ALSO("Multinomial logistic regression (softmax regression) on " + "test_points", "predictions", "predictions")); + +// See also... +BINDING_SEE_ALSO("@logistic_regression", "#logistic_regression"); +BINDING_SEE_ALSO("@random_forest", "#random_forest"); +BINDING_SEE_ALSO("Multinomial logistic regression (softmax regression) on " "Wikipedia", - "https://en.wikipedia.org/wiki/Multinomial_logistic_regression"), - SEE_ALSO("mlpack::regression::SoftmaxRegression C++ class documentation", - "@doxygen/classmlpack_1_1regression_1_1SoftmaxRegression.html")); + "https://en.wikipedia.org/wiki/Multinomial_logistic_regression"); +BINDING_SEE_ALSO("mlpack::regression::SoftmaxRegression C++ class " + "documentation", + "@doxygen/classmlpack_1_1regression_1_1SoftmaxRegression.html"); // Required options. PARAM_MATRIX_IN("training", "A matrix containing the training set (the matrix " diff --git a/src/mlpack/methods/sparse_coding/sparse_coding_main.cpp b/src/mlpack/methods/sparse_coding/sparse_coding_main.cpp index c6977a73f7..15753327b8 100644 --- a/src/mlpack/methods/sparse_coding/sparse_coding_main.cpp +++ b/src/mlpack/methods/sparse_coding/sparse_coding_main.cpp @@ -22,14 +22,19 @@ using namespace mlpack::math; using namespace mlpack::sparse_coding; using namespace mlpack::util; -PROGRAM_INFO("Sparse Coding", - // Short description. +// Program Name. +BINDING_NAME("Sparse Coding"); + +// Short description. +BINDING_SHORT_DESC( "An implementation of Sparse Coding with Dictionary Learning. Given a " "dataset, this will decompose the dataset into a sparse combination of a " "few dictionary elements, where the dictionary is learned during " "computation; a dictionary can be reused for future sparse coding of new " - "points.", - // Long description. + "points."); + +// Long description. +BINDING_LONG_DESC( "An implementation of Sparse Coding with Dictionary Learning, which " "achieves sparsity via an l1-norm regularizer on the codes (LASSO) or an " "(l1+l2)-norm regularizer on the codes (the Elastic Net). Given a dense " @@ -56,8 +61,10 @@ PROGRAM_INFO("Sparse Coding", " an initial dictionary for the optimization, with the " + PRINT_PARAM_STRING("initial_dictionary") + " parameter. An input model may" " be specified with the " + PRINT_PARAM_STRING("input_model") + - " parameter." - "\n\n" + " parameter."); + +// Example. +BINDING_EXAMPLE( "As an example, to build a sparse coding model on the dataset " + PRINT_DATASET("data") + " using 200 atoms and an l1-regularization " "parameter of 0.1, saving the model into " + PRINT_MODEL("model") + ", use " @@ -70,18 +77,20 @@ PROGRAM_INFO("Sparse Coding", PRINT_DATASET("codes") + ": " "\n\n" + PRINT_CALL("sparse_coding", "input_model", "model", "test", "otherdata", - "codes", "codes"), - SEE_ALSO("@local_coordinate_coding", "#local_coordinate_coding"), - SEE_ALSO("Sparse dictionary learning on Wikipedia", - "https://en.wikipedia.org/wiki/Sparse_dictionary_learning"), - SEE_ALSO("Efficient sparse coding algorithms (pdf)", + "codes", "codes")); + +// See also... +BINDING_SEE_ALSO("@local_coordinate_coding", "#local_coordinate_coding"); +BINDING_SEE_ALSO("Sparse dictionary learning on Wikipedia", + "https://en.wikipedia.org/wiki/Sparse_dictionary_learning"); +BINDING_SEE_ALSO("Efficient sparse coding algorithms (pdf)", "http://papers.nips.cc/paper/2979-efficient-sparse-coding-" - "algorithms.pdf"), - SEE_ALSO("Regularization and variable selection via the elastic net", + "algorithms.pdf"); +BINDING_SEE_ALSO("Regularization and variable selection via the elastic net", "http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.124.4696&" - "rep=rep1&type=pdf"), - SEE_ALSO("mlpack::sparse_coding::SparseCoding C++ class documentation", - "@doxygen/classmlpack_1_1sparse__coding_1_1SparseCoding.html")); + "rep=rep1&type=pdf"); +BINDING_SEE_ALSO("mlpack::sparse_coding::SparseCoding C++ class documentation", + "@doxygen/classmlpack_1_1sparse__coding_1_1SparseCoding.html"); // Train the model. PARAM_MATRIX_IN("training", "Matrix of training data (X).", "t"); diff --git a/src/mlpack/tests/CMakeLists.txt b/src/mlpack/tests/CMakeLists.txt index efef3834ce..e882cc767e 100644 --- a/src/mlpack/tests/CMakeLists.txt +++ b/src/mlpack/tests/CMakeLists.txt @@ -9,7 +9,6 @@ add_executable(mlpack_test cli_binding_test.cpp io_test.cpp cosine_tree_test.cpp - cv_test.cpp dbscan_test.cpp dcgan_test.cpp det_test.cpp @@ -75,8 +74,6 @@ add_executable(mlpack_test serialization_test.cpp sfinae_test.cpp sort_policy_test.cpp - sparse_autoencoder_test.cpp - sparse_coding_test.cpp spill_tree_test.cpp string_encoding_test.cpp sumtree_test.cpp @@ -123,7 +120,6 @@ add_executable(mlpack_test main_tests/radical_test.cpp main_tests/random_forest_test.cpp main_tests/range_search_test.cpp - main_tests/sparse_coding_test.cpp main_tests/test_helper.hpp ) @@ -143,6 +139,7 @@ add_executable(mlpack_catch_test block_krylov_svd_test.cpp convolutional_network_test.cpp convolution_test.cpp + cv_test.cpp decision_stump_test.cpp decision_tree_test.cpp image_load_test.cpp @@ -159,6 +156,8 @@ add_executable(mlpack_catch_test serialization_catch.cpp serialization_catch.hpp softmax_regression_test.cpp + sparse_autoencoder_test.cpp + sparse_coding_test.cpp split_data_test.cpp svd_batch_test.cpp svd_incremental_test.cpp @@ -177,6 +176,7 @@ add_executable(mlpack_catch_test main_tests/preprocess_split_test.cpp main_tests/preprocess_imputer_test.cpp main_tests/softmax_regression_test.cpp + main_tests/sparse_coding_test.cpp main_tests/test_helper.hpp ) @@ -229,7 +229,6 @@ set(parallel_tests "LocalCoordinateCodingTest;" "FeedForwardNetworkTest;" "RecurrentNetworkTest;" - "SparseAutoencoderTest;" "GMMTest;" "CFTest;" "HMMTest;" diff --git a/src/mlpack/tests/activation_functions_test.cpp b/src/mlpack/tests/activation_functions_test.cpp index 2637ff045c..2c1fe63398 100644 --- a/src/mlpack/tests/activation_functions_test.cpp +++ b/src/mlpack/tests/activation_functions_test.cpp @@ -909,7 +909,7 @@ TEST_CASE("ElishFunctionTest", "[ActivationFunctionsTest]") desiredDerivatives); } -/** +/** * Basic test of the Soft Shrink function. */ TEST_CASE("SoftShrinkFunctionTest", "[ActivationFunctionsTest]") diff --git a/src/mlpack/tests/ann_layer_test.cpp b/src/mlpack/tests/ann_layer_test.cpp index 028e20575b..2c227afc6d 100644 --- a/src/mlpack/tests/ann_layer_test.cpp +++ b/src/mlpack/tests/ann_layer_test.cpp @@ -451,6 +451,105 @@ TEST_CASE("GradientLinearLayerTest", "[ANNLayerTest]") REQUIRE(CheckGradient(function) <= 1e-4); } +/** + * Simple Linear3D layer test. + */ +TEST_CASE("SimpleLinear3DLayerTest", "[ANNLayerTest]") +{ + const size_t inSize = 4; + const size_t outSize = 1; + const size_t nPoints = 2; + const size_t batchSize = 1; + arma::mat input, output, delta; + + Linear3D<> module(inSize, outSize); + module.Reset(); + module.Parameters().randu(); + + // Test the Forward function. + input = arma::zeros(inSize * nPoints, batchSize); + module.Forward(input, output); + REQUIRE(arma::accu(module.Bias()) + == Approx(arma::accu(output) / (nPoints * batchSize)).epsilon(1e-3)); + + // Test the Backward function. + module.Backward(input, input, delta); + REQUIRE(arma::accu(delta) == 0); +} + +/** + * Jacobian Linear3D module test. + */ +TEST_CASE("JacobianLinear3DLayerTest", "[ANNLayerTest]") +{ + for (size_t i = 0; i < 5; ++i) + { + const size_t inSize = math::RandInt(2, 10); + const size_t outSize = math::RandInt(2, 10); + const size_t nPoints = math::RandInt(2, 10); + const size_t batchSize = 1; + + arma::mat input; + input.set_size(inSize * nPoints, batchSize); + + Linear3D<> module(inSize, outSize); + module.Parameters().randu(); + + double error = JacobianTest(module, input); + REQUIRE(error <= 1e-5); + } +} + +/** + * Simple Gradient test for Linear3D layer. + */ +TEST_CASE("GradientLinear3DLayerTest", "[ANNLayerTest]") +{ + // Linear function gradient instantiation. + struct GradientFunction + { + GradientFunction() + { + const size_t inSize = 4; + const size_t outSize = 1; + const size_t nPoints = 2; + const size_t batchSize = 4; + + input = arma::randu(inSize * nPoints, batchSize); + target = arma::zeros(outSize * nPoints, batchSize); + target(0, 0) = 1; + target(0, 3) = 1; + target(1, 1) = 1; + target(1, 2) = 1; + + model = new FFN, RandomInitialization>(); + model->Predictors() = input; + model->Responses() = target; + model->Add>(); + model->Add>(inSize, outSize); + } + + ~GradientFunction() + { + delete model; + } + + double Gradient(arma::mat& gradient) const + { + double error = model->Evaluate(model->Parameters(), 0, 1); + model->Gradient(model->Parameters(), 0, gradient, 1); + return error; + } + + arma::mat& Parameters() { return model->Parameters(); } + + FFN, RandomInitialization>* model; + arma::mat input, target; + } function; + + REQUIRE(CheckGradient(function) <= 1e-7); +} + /** * Simple noisy linear module test. */ @@ -1670,7 +1769,7 @@ TEST_CASE("SimpleLookupLayerTest", "[ANNLayerTest]") for (size_t i = 0; i < batchSize; ++i) { // The Lookup module uses index - 1 for the cols. - const double outputSum = arma::accu(module.Parameters().rows( + const double outputSum = arma::accu(module.Parameters().cols( arma::conv_to::from(input.col(i)) - 1)); REQUIRE(std::fabs(outputSum - arma::accu(output.col(i))) <= 1e-5); @@ -4412,3 +4511,238 @@ TEST_CASE("SpatialDropoutLayerParametersTest", "[ANNLayerTest]") REQUIRE(layer.Size() == 3); REQUIRE(layer.Ratio() == 0.2); } + +/** + * Simple Positional Encoding layer test. + */ +TEST_CASE("SimplePositionalEncodingTest", "[ANNLayerTest]") +{ + const size_t seqLength = 5; + const size_t embedDim = 4; + const size_t batchSize = 2; + + arma::mat input = arma::randu(embedDim * seqLength, batchSize); + arma::mat gy = 0.01 * arma::randu(embedDim * seqLength, batchSize); + arma::mat output, g; + + PositionalEncoding<> module(embedDim, seqLength); + + // Check Forward function. + module.Forward(input, output); + arma::mat pe = output - input; + CheckMatrices(arma::mean(pe, 1), module.Encoding()); + + // Check Backward function. + module.Backward(input, gy, g); + REQUIRE(std::equal(gy.begin(), gy.end(), g.begin())); +} + +/** + * Jacobian test for Positional Encoding layer. + */ +TEST_CASE("JacobianPositionalEncodingTest", "[ANNLayerTest]") +{ + for (size_t i = 0; i < 5; ++i) + { + const size_t embedDim = 4; + const size_t seqLength = math::RandInt(5, 10); + arma::mat input; + input.set_size(embedDim * seqLength, 1); + + PositionalEncoding<> module(embedDim, seqLength); + + double error = JacobianTest(module, input); + REQUIRE(error <= 1e-5); + } +} + +/** + * Simple Multihead Attention test. + */ +TEST_CASE("SimpleMultiheadAttentionTest", "[ANNLayerTest]") +{ + size_t tLen = 5; + size_t sLen = tLen; + size_t embedDim = 4; + size_t numHeads = 2; + size_t bsz = 3; + + arma::mat query = 0.1 * arma::randu(embedDim * tLen, bsz); + arma::mat output; + + arma::mat attnMask = arma::zeros(tLen, sLen); + for (size_t i = 0; i < tLen; ++i) + { + for (size_t j = 0; j < sLen; ++j) + { + if (i < j) + attnMask(i, j) = std::numeric_limits::lowest(); + } + } + + arma::mat keyPaddingMask = arma::zeros(1, sLen); + keyPaddingMask(sLen - 1) = std::numeric_limits::lowest(); + + MultiheadAttention<> module(tLen, sLen, embedDim, numHeads); + module.AttentionMask() = attnMask; + module.KeyPaddingMask() = keyPaddingMask; + module.Reset(); + module.Parameters().randu(); + + // Forward test. + arma::mat input = arma::join_cols(arma::join_cols(query, query), query); + + module.Forward(input, output); + REQUIRE(output.n_rows == embedDim * tLen); + REQUIRE(output.n_cols == bsz); + + // Backward test. + arma::mat gy = 0.01 * arma::randu(embedDim * tLen, bsz); + arma::mat g; + module.Backward(input, gy, g); + REQUIRE(g.n_rows == input.n_rows); + REQUIRE(g.n_cols == input.n_cols); + + // Gradient test. + arma::mat error = 0.05 * arma::randu(embedDim * tLen, bsz); + arma::mat gradient; + module.Gradient(input, error, gradient); + REQUIRE(gradient.n_rows == module.Parameters().n_rows); + REQUIRE(gradient.n_cols == module.Parameters().n_cols); +} + +/** + * Jacobian MultiheadAttention module test. + */ +TEST_CASE("JacobianMultiheadAttentionTest", "[ANNLayerTest]") +{ + // Check when query = key = value. + for (size_t i = 0; i < 5; ++i) + { + const size_t tgtSeqLen = 2; + const size_t embedDim = 4; + const size_t nHeads = 2; + const size_t batchSize = 1; + + arma::mat query = arma::randu(embedDim * tgtSeqLen, batchSize); + arma::mat input = arma::join_cols(arma::join_cols(query, query), query); + + MultiheadAttention<> module(tgtSeqLen, tgtSeqLen, embedDim, nHeads); + module.Parameters().randu(); + + double error = CustomJacobianTest(module, input); + REQUIRE(error <= 1e-5); + } + + // Check when key = value. + for (size_t i = 0; i < 5; ++i) + { + const size_t tgtSeqLen = 2; + const size_t srcSeqLen = math::RandInt(2, 5); + const size_t embedDim = 4; + const size_t nHeads = 2; + const size_t batchSize = 1; + + arma::mat query = arma::randu(embedDim * tgtSeqLen, batchSize); + arma::mat key = 0.091 * arma::randu(embedDim * srcSeqLen, batchSize); + arma::mat input = arma::join_cols(arma::join_cols(query, key), key); + + MultiheadAttention<> module(tgtSeqLen, srcSeqLen, embedDim, nHeads); + module.Parameters().randu(); + + double error = CustomJacobianTest(module, input); + REQUIRE(error <= 1e-5); + } + + // Check when query, key and value are not same. + for (size_t i = 0; i < 5; ++i) + { + const size_t tgtSeqLen = 2; + const size_t srcSeqLen = math::RandInt(2, 5); + const size_t embedDim = 4; + const size_t nHeads = 2; + const size_t batchSize = 1; + + arma::mat query = arma::randu(embedDim * tgtSeqLen, batchSize); + arma::mat key = 0.091 * arma::randu(embedDim * srcSeqLen, batchSize); + arma::mat value = 0.045 * arma::randu(embedDim * srcSeqLen, batchSize); + arma::mat input = arma::join_cols(arma::join_cols(query, key), value); + + MultiheadAttention<> module(tgtSeqLen, srcSeqLen, embedDim, nHeads); + module.Parameters().randu(); + + double error = JacobianTest(module, input); + REQUIRE(error <= 1e-5); + } +} + +/** + * Numerical gradient test for MultiheadAttention layer. + */ +TEST_CASE("GradientMultiheadAttentionTest", "[ANNLayerTest]") +{ + struct GradientFunction + { + GradientFunction() + { + input = arma::randu(embedDim * (tgtSeqLen + 2 * srcSeqLen), batchSize); + target = arma::zeros(vocabSize, batchSize); + for (size_t i = 0; i < target.n_elem; ++i) + { + const size_t label = mlpack::math::RandInt(1, vocabSize); + target(i) = label; + } + + attnMask = arma::zeros(tgtSeqLen, srcSeqLen); + for (size_t i = 0; i < tgtSeqLen; ++i) + { + for (size_t j = 0; j < srcSeqLen; ++j) + { + if (i < j) + attnMask(i, j) = std::numeric_limits::lowest(); + } + } + + keyPaddingMask = arma::zeros(1, srcSeqLen); + keyPaddingMask(srcSeqLen - 1) = std::numeric_limits::lowest(); + + model = new FFN, XavierInitialization>(); + model->Predictors() = input; + model->Responses() = target; + attnModule = new MultiheadAttention<>(tgtSeqLen, srcSeqLen, + embedDim, nHeads); + attnModule->AttentionMask() = attnMask; + attnModule->KeyPaddingMask() = keyPaddingMask; + model->Add(attnModule); + model->Add>(embedDim * tgtSeqLen, vocabSize); + model->Add>(); + } + + ~GradientFunction() + { + delete model; + } + + double Gradient(arma::mat& gradient) const + { + double error = model->Evaluate(model->Parameters(), 0, batchSize); + model->Gradient(model->Parameters(), 0, gradient, batchSize); + return error; + } + + arma::mat& Parameters() { return model->Parameters(); } + + FFN, XavierInitialization>* model; + MultiheadAttention<>* attnModule; + + arma::mat input, target, attnMask, keyPaddingMask; + const size_t tgtSeqLen = 2; + const size_t srcSeqLen = 2; + const size_t embedDim = 4; + const size_t nHeads = 2; + const size_t vocabSize = 5; + const size_t batchSize = 2; + } function; + + REQUIRE(CheckGradient(function) <= 1e-06); +} diff --git a/src/mlpack/tests/ann_test_tools.hpp b/src/mlpack/tests/ann_test_tools.hpp index 3064ddb767..dff9bbf5a9 100644 --- a/src/mlpack/tests/ann_test_tools.hpp +++ b/src/mlpack/tests/ann_test_tools.hpp @@ -98,6 +98,57 @@ double JacobianTest(ModuleType& module, return arma::max(arma::max(arma::abs(jacobianA - jacobianB))); } +// Custom Jacobian Test where we get the input from outside of this function +// unlike the original Jacobian Test where input is generated inside that +// funcion. +template +double CustomJacobianTest(ModuleType& module, + arma::mat& input, + const double perturbation = 1e-6) +{ + arma::mat output, outputA, outputB, jacobianA, jacobianB; + + // Initialize the module parameters. + ResetFunction(module); + + // Initialize the jacobian matrix. + module.Forward(input, output); + jacobianA = arma::zeros(input.n_elem, output.n_elem); + + for (size_t i = 0; i < input.n_elem; ++i) + { + double original = input(i); + input(i) = original - perturbation; + module.Forward(input, outputA); + input(i) = original + perturbation; + module.Forward(input, outputB); + input(i) = original; + + outputB -= outputA; + outputB /= 2 * perturbation; + jacobianA.row(i) = outputB.t(); + } + + // Initialize the derivative parameter. + arma::mat deriv = arma::zeros(output.n_rows, output.n_cols); + + // Initialize the jacobian matrix. + jacobianB = arma::zeros(input.n_elem, output.n_elem); + + for (size_t i = 0; i < deriv.n_elem; ++i) + { + deriv.zeros(); + deriv(i) = 1; + + arma::mat delta; + module.Backward(input, deriv, delta); + + jacobianB.col(i) = delta; + } + + return arma::max(arma::max(arma::abs(jacobianA - jacobianB))); +} + // Approximate Jacobian and supposedly-true Jacobian, then compare them // similarly to before. template diff --git a/src/mlpack/tests/cv_test.cpp b/src/mlpack/tests/cv_test.cpp index 1407a6102e..635afb761f 100644 --- a/src/mlpack/tests/cv_test.cpp +++ b/src/mlpack/tests/cv_test.cpp @@ -36,7 +36,7 @@ #include #include -#include +#include "catch.hpp" #include "mock_categorical_data.hpp" using namespace mlpack; @@ -47,12 +47,10 @@ using namespace mlpack::regression; using namespace mlpack::tree; using namespace mlpack::data; -BOOST_AUTO_TEST_SUITE(CVTest); - /** * Test metrics for binary classification. */ -BOOST_AUTO_TEST_CASE(BinaryClassificationMetricsTest) +TEST_CASE("BinaryClassificationMetricsTest", "[CVTest]") { // Using the same data for training and testing. arma::mat data = arma::linspace(1.0, 10.0, 10); @@ -66,20 +64,22 @@ BOOST_AUTO_TEST_CASE(BinaryClassificationMetricsTest) LogisticRegression<> lr(data, predictedLabels); - BOOST_REQUIRE_CLOSE(Accuracy::Evaluate(lr, data, labels), 0.7, 1e-5); + REQUIRE(Accuracy::Evaluate(lr, data, labels) == Approx(0.7).epsilon(1e-7)); - BOOST_REQUIRE_CLOSE(Precision::Evaluate(lr, data, labels), 0.6, 1e-5); + REQUIRE(Precision::Evaluate(lr, data, labels) + == Approx(0.6).epsilon(1e-7)); - BOOST_REQUIRE_CLOSE(Recall::Evaluate(lr, data, labels), 0.75, 1e-5); + REQUIRE(Recall::Evaluate(lr, data, labels) + == Approx(0.75).epsilon(1e-7)); double f1 = 2 * 0.6 * 0.75 / (0.6 + 0.75); - BOOST_REQUIRE_CLOSE(F1::Evaluate(lr, data, labels), f1, 1e-5); + REQUIRE(F1::Evaluate(lr, data, labels) == Approx(f1).epsilon(1e-7)); } /** * Test for confusion matrix. */ -BOOST_AUTO_TEST_CASE(ConfusionMatrixTest) +TEST_CASE("ConfusionMatrixTest", "[CVTest]") { // Labels that will be considered as "ground truth". arma::Row labels("0 0 1 0 0 1 0 1 0 1"); @@ -89,16 +89,16 @@ BOOST_AUTO_TEST_CASE(ConfusionMatrixTest) // Confusion matrix. arma::Mat output; data::ConfusionMatrix(predictedLabels, labels, output, 2); - BOOST_REQUIRE_EQUAL(output(0, 0), 4); - BOOST_REQUIRE_EQUAL(output(0, 1), 1); - BOOST_REQUIRE_EQUAL(output(1, 0), 2); - BOOST_REQUIRE_EQUAL(output(1, 1), 3); + REQUIRE(output(0, 0) == 4); + REQUIRE(output(0, 1) == 1); + REQUIRE(output(1, 0) == 2); + REQUIRE(output(1, 1) == 3); } /** * Test metrics for multiclass classification. */ -BOOST_AUTO_TEST_CASE(MulticlassClassificationMetricsTest) +TEST_CASE("MulticlassClassificationMetricsTest", "[CVTest]") { // Using the same data for training and testing. arma::mat data = arma::linspace(1.0, 12.0, 12); @@ -115,40 +115,41 @@ BOOST_AUTO_TEST_CASE(MulticlassClassificationMetricsTest) // Assert that the Naive Bayes model really predicts the labels above in // response to the data. - BOOST_REQUIRE_CLOSE(Accuracy::Evaluate(nb, data, predictedLabels), 1.0, 1e-5); + REQUIRE(Accuracy::Evaluate(nb, data, predictedLabels) + == Approx(1.0).epsilon(1e-7)); double microaveragedPrecision = double(1 + 1 + 3 + 4) / 12; - BOOST_REQUIRE_CLOSE(Precision::Evaluate(nb, data, labels), - microaveragedPrecision, 1e-5); + REQUIRE(Precision::Evaluate(nb, data, labels) + == Approx(microaveragedPrecision).epsilon(1e-7)); double microaveragedRecall = double(1 + 1 + 3 + 4) / 12; - BOOST_REQUIRE_CLOSE(Recall::Evaluate(nb, data, labels), - microaveragedRecall, 1e-5); + REQUIRE(Recall::Evaluate(nb, data, labels) + == Approx(microaveragedRecall).epsilon(1e-7)); double microaveragedF1 = 2 * microaveragedPrecision * microaveragedRecall / (microaveragedPrecision + microaveragedRecall); - BOOST_REQUIRE_CLOSE(F1::Evaluate(nb, data, labels), - microaveragedF1, 1e-5); + REQUIRE(F1::Evaluate(nb, data, labels) + == Approx(microaveragedF1).epsilon(1e-7)); double macroaveragedPrecision = (0.5 + 0.5 + 0.75 + 1.0) / 4; - BOOST_REQUIRE_CLOSE(Precision::Evaluate(nb, data, labels), - macroaveragedPrecision, 1e-5); + REQUIRE(Precision::Evaluate(nb, data, labels) + == Approx(macroaveragedPrecision).epsilon(1e-7)); double macroaveragedRecall = (0.5 + 1.0 / 3 + 1.0 + 1.0) / 4; - BOOST_REQUIRE_CLOSE(Recall::Evaluate(nb, data, labels), - macroaveragedRecall, 1e-5); + REQUIRE(Recall::Evaluate(nb, data, labels) + == Approx(macroaveragedRecall).epsilon(1e-7)); double macroaveragedF1 = (2 * 0.5 * 0.5 / (0.5 + 0.5) + 2 * 0.5 * (1.0 / 3) / (0.5 + (1.0 / 3)) + 2 * 0.75 * 1.0 / (0.75 + 1.0) + 2 * 1.0 * 1.0 / (1.0 + 1.0)) / 4; - BOOST_REQUIRE_CLOSE(F1::Evaluate(nb, data, labels), - macroaveragedF1, 1e-5); + REQUIRE(F1::Evaluate(nb, data, labels) + == Approx(macroaveragedF1).epsilon(1e-7)); } /** * Test the mean squared error. */ -BOOST_AUTO_TEST_CASE(MSETest) +TEST_CASE("MSETest", "[CVTest]") { // Making two points that define the linear function f(x) = x - 1 arma::mat trainingData("0 1"); @@ -163,13 +164,14 @@ BOOST_AUTO_TEST_CASE(MSETest) double expectedMSE = (0 * 0 + 1 * 1 + 2 * 2) / 3.0; - BOOST_REQUIRE_CLOSE(MSE::Evaluate(lr, data, responses), expectedMSE, 1e-5); + REQUIRE(MSE::Evaluate(lr, data, responses) + == Approx(expectedMSE).epsilon(1e-7)); } /** * Test the R squared metric (R2 Score). */ -BOOST_AUTO_TEST_CASE(R2ScoreTest) +TEST_CASE("R2ScoreTest", "[CVTest]") { // Making two points that define the linear function f(x) = x - 1. arma::mat trainingData("0 1"); @@ -185,13 +187,14 @@ BOOST_AUTO_TEST_CASE(R2ScoreTest) double expectedR2 = 0.99999779; - BOOST_REQUIRE_CLOSE(R2Score::Evaluate(lr, data, responses), expectedR2, 1e-5); + REQUIRE(R2Score::Evaluate(lr, data, responses) + == Approx(expectedR2).epsilon(1e-7)); } /** * Test the mean squared error with matrix responses. */ -BOOST_AUTO_TEST_CASE(MSEMatResponsesTest) +TEST_CASE("MSEMatResponsesTest", "[CVTest]") { arma::mat data("1 2"); arma::mat trainingResponses("1 2; 3 4"); @@ -212,7 +215,8 @@ BOOST_AUTO_TEST_CASE(MSEMatResponsesTest) double expectedMSE = (0 * 0 + 1 * 1 + 2 * 2 + 3 * 3) / 4.0; - BOOST_REQUIRE_CLOSE(MSE::Evaluate(ffn, data, responses), expectedMSE, 1e-1); + REQUIRE(MSE::Evaluate(ffn, data, responses) + == Approx(expectedMSE).epsilon(1e-3)); } template(); // CheckPredictionsType, arma::mat>(); @@ -250,7 +254,7 @@ BOOST_AUTO_TEST_CASE(PredictionsTypeTest) * Test MetaInfoExtractor correctly identifies whether a given machine learning * algorithm supports weighted learning. */ -BOOST_AUTO_TEST_CASE(SupportsWeightsTest) +TEST_CASE("SupportsWeightsTest", "[CVTest]") { static_assert(MetaInfoExtractor::SupportsWeights, "Value should be true"); @@ -282,7 +286,7 @@ void CheckWeightsType() * Test MetaInfoExtractor correctly recognizes the type of weights for a given * machine learning algorithm. */ -BOOST_AUTO_TEST_CASE(WeightsTypeTest) +TEST_CASE("WeightsTypeTest", "[CVTest]") { CheckWeightsType(); CheckWeightsType, arma::rowvec>(); @@ -294,7 +298,7 @@ BOOST_AUTO_TEST_CASE(WeightsTypeTest) * Test MetaInfoExtractor correctly identifies whether a given machine learning * algorithm takes a data:DatasetInfo parameter. */ -BOOST_AUTO_TEST_CASE(TakesDatasetInfoTest) +TEST_CASE("TakesDatasetInfoTest", "[CVTest]") { static_assert(MetaInfoExtractor>::TakesDatasetInfo, "Value should be true"); @@ -308,7 +312,7 @@ BOOST_AUTO_TEST_CASE(TakesDatasetInfoTest) * Test MetaInfoExtractor correctly identifies whether a given machine learning * algorithm takes the numClasses parameter. */ -BOOST_AUTO_TEST_CASE(TakesNumClassesTest) +TEST_CASE("TakesNumClassesTest", "[CVTest]") { static_assert(MetaInfoExtractor>::TakesNumClasses, "Value should be true"); @@ -324,7 +328,7 @@ BOOST_AUTO_TEST_CASE(TakesNumClassesTest) * Test the simple cross-validation strategy implementation with the Accuracy * metric. */ -BOOST_AUTO_TEST_CASE(SimpleCVAccuracyTest) +TEST_CASE("SimpleCVAccuracyTest", "[CVTest]") { // Using the first half of data for training and the rest for validation. // The validation labels are 75% correct. @@ -334,13 +338,13 @@ BOOST_AUTO_TEST_CASE(SimpleCVAccuracyTest) SimpleCV, Accuracy> cv(0.5, data, labels); - BOOST_REQUIRE_CLOSE(cv.Evaluate(), 0.75, 1e-5); + REQUIRE(cv.Evaluate() == Approx(0.75).epsilon(1e-7)); } /** * Test the simple cross-validation strategy implementation with the MSE metric. */ -BOOST_AUTO_TEST_CASE(SimpleCVMSETest) +TEST_CASE("SimpleCVMSETest", "[CVTest]") { // Using the first two points for training and remaining three for validation. // See the test MSETest for more explanation. @@ -351,7 +355,7 @@ BOOST_AUTO_TEST_CASE(SimpleCVMSETest) SimpleCV cv(0.6, data, responses); - BOOST_REQUIRE_CLOSE(cv.Evaluate(), expectedMSE, 1e-5); + REQUIRE(cv.Evaluate() == Approx(expectedMSE).epsilon(1e-7)); arma::mat noiseData("-1 -2 -3 -4 -5"); arma::rowvec noiseResponses("10 20 30 40 50"); @@ -365,7 +369,7 @@ BOOST_AUTO_TEST_CASE(SimpleCVMSETest) SimpleCV weightedCV(0.3, allData, allResponces, weights); - BOOST_REQUIRE_CLOSE(weightedCV.Evaluate(), expectedMSE, 1e-5); + REQUIRE(weightedCV.Evaluate() == Approx(expectedMSE).epsilon(1e-7)); arma::rowvec weights2 = arma::join_rows(arma::zeros(noiseData.n_cols - 1).t(), arma::ones(data.n_cols + 1).t()); @@ -373,7 +377,7 @@ BOOST_AUTO_TEST_CASE(SimpleCVMSETest) SimpleCV weightedCV2(0.3, allData, allResponces, weights2); - BOOST_REQUIRE_GT(std::abs(weightedCV2.Evaluate() - expectedMSE), 1e-5); + REQUIRE(std::abs(weightedCV2.Evaluate() - expectedMSE) > 1e-5); } template @@ -390,7 +394,7 @@ arma::Row PredictLabelsWithDT(const arma::mat& data, * Test the simple cross-validation strategy implementation with decision trees * constructed in multiple ways. */ -BOOST_AUTO_TEST_CASE(SimpleCVWithDTTest) +TEST_CASE("SimpleCVWithDTTest", "[CVTest]") { arma::mat data; arma::Row labels; @@ -411,21 +415,21 @@ BOOST_AUTO_TEST_CASE(SimpleCVWithDTTest) trainingData, trainingLabels, numClasses, minimumLeafSize); SimpleCV, Accuracy> cv(0.5, data, arma::join_rows(trainingLabels, predictedLabels), numClasses); - BOOST_REQUIRE_CLOSE(cv.Evaluate(minimumLeafSize), 1.0, 1e-5); + REQUIRE(cv.Evaluate(minimumLeafSize) == Approx(1.0).epsilon(1e-7)); } { arma::Row predictedLabels = PredictLabelsWithDT(testData, trainingData, datasetInfo, trainingLabels, numClasses, minimumLeafSize); SimpleCV, Accuracy> cv(0.5, data, datasetInfo, arma::join_rows(trainingLabels, predictedLabels), numClasses); - BOOST_REQUIRE_CLOSE(cv.Evaluate(minimumLeafSize), 1.0, 1e-5); + REQUIRE(cv.Evaluate(minimumLeafSize) == Approx(1.0).epsilon(1e-7)); } { arma::Row predictedLabels = PredictLabelsWithDT(testData, trainingData, trainingLabels, numClasses, weights, minimumLeafSize); SimpleCV, Accuracy> cv(0.5, data, arma::join_rows(trainingLabels, predictedLabels), numClasses, weights); - BOOST_REQUIRE_CLOSE(cv.Evaluate(minimumLeafSize), 1.0, 1e-5); + REQUIRE(cv.Evaluate(minimumLeafSize) == Approx(1.0).epsilon(1e-7)); } { arma::Row predictedLabels = PredictLabelsWithDT(testData, @@ -433,14 +437,14 @@ BOOST_AUTO_TEST_CASE(SimpleCVWithDTTest) minimumLeafSize); SimpleCV, Accuracy> cv(0.5, data, datasetInfo, arma::join_rows(trainingLabels, predictedLabels), numClasses, weights); - BOOST_REQUIRE_CLOSE(cv.Evaluate(minimumLeafSize), 1.0, 1e-5); + REQUIRE(cv.Evaluate(minimumLeafSize) == Approx(1.0).epsilon(1e-7)); } } /** * Test k-fold cross-validation with the MSE metric. */ -BOOST_AUTO_TEST_CASE(KFoldCVMSETest) +TEST_CASE("KFoldCVMSETest", "[CVTest]") { // Defining dataset with two sets of responses for the same two data points. arma::mat data("0 1 0 1"); @@ -453,17 +457,17 @@ BOOST_AUTO_TEST_CASE(KFoldCVMSETest) double expectedMSE = double((1 - 0) * (1 - 0) + (3 - 1) * (3 - 1)) / 2 * 2 / 2; - BOOST_REQUIRE_CLOSE(cv.Evaluate(), expectedMSE, 1e-5); + REQUIRE(cv.Evaluate() == Approx(expectedMSE).epsilon(1e-7)); // Assert we can access a trained model without the exception of // uninitialization. - cv.Model(); + REQUIRE_NOTHROW(cv.Model()); } /** * Test k-fold cross-validation with the Accuracy metric. */ -BOOST_AUTO_TEST_CASE(KFoldCVAccuracyTest) +TEST_CASE("KFoldCVAccuracyTest", "[CVTest]") { // Making a 10-points dataset. The last point should be classified wrong when // it is tested separately. @@ -479,17 +483,17 @@ BOOST_AUTO_TEST_CASE(KFoldCVAccuracyTest) // fail with the remaining one. double expectedAccuracy = (9 * 1.0 + 0.0) / 10; - BOOST_REQUIRE_CLOSE(cv.Evaluate(), expectedAccuracy, 1e-5); + REQUIRE(cv.Evaluate() == Approx(expectedAccuracy).epsilon(1e-7)); // Assert we can access a trained model without the exception of // uninitialization. - cv.Model(); + REQUIRE_NOTHROW(cv.Model()); } /** * Test k-fold cross-validation with weighted linear regression. */ -BOOST_AUTO_TEST_CASE(KFoldCVWithWeightedLRTest) +TEST_CASE("KFoldCVWithWeightedLRTest", "[CVTest]") { // Each fold will be filled with this dataset. arma::mat data("1 2 3 4"); @@ -506,14 +510,14 @@ BOOST_AUTO_TEST_CASE(KFoldCVWithWeightedLRTest) double mse = MSE::Evaluate(cv.Model(), testData, testResponses); - BOOST_REQUIRE_CLOSE(1.0 - mse, 1.0, 1e-5); + REQUIRE((1.0 - mse) == Approx(1.0).epsilon(1e-7)); } /** * Test k-fold cross-validation with decision trees constructed in multiple * ways. */ -BOOST_AUTO_TEST_CASE(KFoldCVWithDTTest) +TEST_CASE("KFoldCVWithDTTest", "[CVTest]") { arma::mat originalData; arma::Row originalLabels; @@ -539,7 +543,7 @@ BOOST_AUTO_TEST_CASE(KFoldCVWithDTTest) arma::Row predictedLabels = PredictLabelsWithDT(data, data, labels, numClasses, minimumLeafSize); double accuracy = Accuracy::Evaluate(cv.Model(), data, predictedLabels); - BOOST_REQUIRE_CLOSE(accuracy, 1.0, 1e-5); + REQUIRE(accuracy == Approx(1.0).epsilon(1e-7)); } { KFoldCV, Accuracy> cv(2, doubledData, @@ -548,7 +552,7 @@ BOOST_AUTO_TEST_CASE(KFoldCVWithDTTest) arma::Row predictedLabels = PredictLabelsWithDT(data, data, datasetInfo, labels, numClasses, minimumLeafSize); double accuracy = Accuracy::Evaluate(cv.Model(), data, predictedLabels); - BOOST_REQUIRE_CLOSE(accuracy, 1.0, 1e-5); + REQUIRE(accuracy == Approx(1.0).epsilon(1e-7)); } { KFoldCV, Accuracy> cv(2, doubledData, @@ -557,7 +561,7 @@ BOOST_AUTO_TEST_CASE(KFoldCVWithDTTest) arma::Row predictedLabels = PredictLabelsWithDT(data, data, labels, numClasses, weights, minimumLeafSize); double accuracy = Accuracy::Evaluate(cv.Model(), data, predictedLabels); - BOOST_REQUIRE_CLOSE(accuracy, 1.0, 1e-5); + REQUIRE(accuracy == Approx(1.0).epsilon(1e-7)); } { KFoldCV, Accuracy> cv(2, doubledData, @@ -566,7 +570,7 @@ BOOST_AUTO_TEST_CASE(KFoldCVWithDTTest) arma::Row predictedLabels = PredictLabelsWithDT(data, data, datasetInfo, labels, numClasses, weights, minimumLeafSize); double accuracy = Accuracy::Evaluate(cv.Model(), data, predictedLabels); - BOOST_REQUIRE_CLOSE(accuracy, 1.0, 1e-5); + REQUIRE(accuracy == Approx(1.0).epsilon(1e-7)); } } @@ -574,7 +578,7 @@ BOOST_AUTO_TEST_CASE(KFoldCVWithDTTest) * Test k-fold cross-validation with decision trees constructed in multiple * ways, but with larger k and no shuffling. */ -BOOST_AUTO_TEST_CASE(KFoldCVWithDTTestLargeKNoShuffle) +TEST_CASE("KFoldCVWithDTTestLargeKNoShuffle", "[CVTest]") { arma::mat data; arma::Row labels; @@ -591,7 +595,7 @@ BOOST_AUTO_TEST_CASE(KFoldCVWithDTTestLargeKNoShuffle) // This is a very loose tolerance, but we expect about the same as we would // from an individual decision tree training. - BOOST_REQUIRE_GT(accuracy, 0.7); + REQUIRE(accuracy > 0.7); } /** @@ -600,7 +604,7 @@ BOOST_AUTO_TEST_CASE(KFoldCVWithDTTestLargeKNoShuffle) * cross-validation bin is not even (the last is smaller), and also with no * shuffling. */ -BOOST_AUTO_TEST_CASE(KFoldCVWithDTTestUnevenBinsNoShuffle) +TEST_CASE("KFoldCVWithDTTestUnevenBinsNoShuffle", "[CVTest]") { arma::mat data; arma::Row labels; @@ -617,14 +621,14 @@ BOOST_AUTO_TEST_CASE(KFoldCVWithDTTestUnevenBinsNoShuffle) // This is a very loose tolerance, but we expect about the same as we would // from an individual decision tree training. - BOOST_REQUIRE_GT(accuracy, 0.7); + REQUIRE(accuracy > 0.7); } /** * Test k-fold cross-validation with decision trees constructed in multiple * ways, but with larger k. */ -BOOST_AUTO_TEST_CASE(KFoldCVWithDTTestLargeK) +TEST_CASE("KFoldCVWithDTTestLargeK", "[CVTest]") { arma::mat data; arma::Row labels; @@ -641,7 +645,7 @@ BOOST_AUTO_TEST_CASE(KFoldCVWithDTTestLargeK) // This is a very loose tolerance, but we expect about the same as we would // from an individual decision tree training. - BOOST_REQUIRE_GT(accuracy, 0.7); + REQUIRE(accuracy > 0.7); } /** @@ -649,7 +653,7 @@ BOOST_AUTO_TEST_CASE(KFoldCVWithDTTestLargeK) * ways, but with larger k such that the number of points in each * cross-validation bin is not even (the last is smaller). */ -BOOST_AUTO_TEST_CASE(KFoldCVWithDTTestUnevenBins) +TEST_CASE("KFoldCVWithDTTestUnevenBins", "[CVTest]") { arma::mat data; arma::Row labels; @@ -666,14 +670,14 @@ BOOST_AUTO_TEST_CASE(KFoldCVWithDTTestUnevenBins) // This is a very loose tolerance, but we expect about the same as we would // from an individual decision tree training. - BOOST_REQUIRE_GT(accuracy, 0.7); + REQUIRE(accuracy > 0.7); } /** * Test k-fold cross-validation with decision trees constructed in multiple * ways, but with larger k and weights. */ -BOOST_AUTO_TEST_CASE(KFoldCVWithDTTestLargeKWeighted) +TEST_CASE("KFoldCVWithDTTestLargeKWeighted", "[CVTest]") { arma::mat data; arma::Row labels; @@ -691,7 +695,7 @@ BOOST_AUTO_TEST_CASE(KFoldCVWithDTTestLargeKWeighted) // This is a very loose tolerance, but we expect about the same as we would // from an individual decision tree training. - BOOST_REQUIRE_GT(accuracy, 0.7); + REQUIRE(accuracy > 0.7); } /** @@ -699,7 +703,7 @@ BOOST_AUTO_TEST_CASE(KFoldCVWithDTTestLargeKWeighted) * ways, but with larger k such that the number of points in each * cross-validation bin is not even (the last is smaller) and weights. */ -BOOST_AUTO_TEST_CASE(KFoldCVWithDTTestUnevenBinsWeighted) +TEST_CASE("KFoldCVWithDTTestUnevenBinsWeighted", "[CVTest]") { arma::mat data; arma::Row labels; @@ -717,13 +721,13 @@ BOOST_AUTO_TEST_CASE(KFoldCVWithDTTestUnevenBinsWeighted) // This is a very loose tolerance, but we expect about the same as we would // from an individual decision tree training. - BOOST_REQUIRE_GT(accuracy, 0.7); + REQUIRE(accuracy > 0.7); } /** * Test Silhouette Score */ -BOOST_AUTO_TEST_CASE(SilhouetteScoreTest) +TEST_CASE("SilhouetteScoreTest", "[CVTest]") { arma::mat X; X << 0 << 1 << 1 << 0 << 0 << arma::endr @@ -732,7 +736,5 @@ BOOST_AUTO_TEST_CASE(SilhouetteScoreTest) arma::Row labels = {0, 1, 2, 0, 0}; metric::EuclideanDistance metric; double silhouetteScore = SilhouetteScore::Overall(X, labels, metric); - BOOST_REQUIRE_CLOSE(silhouetteScore, 0.1121684822489150, 1e-5); + REQUIRE(silhouetteScore == Approx(0.1121684822489150).epsilon(1e-7)); } - -BOOST_AUTO_TEST_SUITE_END(); diff --git a/src/mlpack/tests/logistic_regression_test.cpp b/src/mlpack/tests/logistic_regression_test.cpp index d34b92e093..38f7a966c8 100644 --- a/src/mlpack/tests/logistic_regression_test.cpp +++ b/src/mlpack/tests/logistic_regression_test.cpp @@ -1023,4 +1023,38 @@ BOOST_AUTO_TEST_CASE(ConstructionThenTraining) BOOST_REQUIRE_NO_THROW(lr.Train(myMatrix, myTargets)); } +/** + * Make sure that incremental training works. + */ +BOOST_AUTO_TEST_CASE(IncrementalTraining) +{ + // Generate a two-Gaussian dataset. + GaussianDistribution g1(arma::vec("1.0 1.0 1.0"), arma::eye(3, 3)); + GaussianDistribution g2(arma::vec("9.0 9.0 9.0"), arma::eye(3, 3)); + + arma::mat data(3, 1000); + arma::Row responses(1000); + for (size_t i = 0; i < 500; ++i) + { + data.col(i) = g1.Random(); + responses[i] = 0; + } + for (size_t i = 500; i < 1000; ++i) + { + data.col(i) = g2.Random(); + responses[i] = 1; + } + + // Now train a logistic regression object on it. + LogisticRegression<> lr(data.n_rows, 0.5); + for (size_t epoch = 0; epoch < 10; ++epoch) + for (size_t i = 0; i < data.n_cols; ++i) + lr.Train(data, responses); + + // Ensure that the error is close to zero. + const double acc = lr.ComputeAccuracy(data, responses); + + BOOST_REQUIRE_CLOSE(acc, 100.0, 3.0); // 3% error tolerance. +} + BOOST_AUTO_TEST_SUITE_END(); diff --git a/src/mlpack/tests/main_tests/sparse_coding_test.cpp b/src/mlpack/tests/main_tests/sparse_coding_test.cpp index a2f5b2b18c..49eedb92b8 100644 --- a/src/mlpack/tests/main_tests/sparse_coding_test.cpp +++ b/src/mlpack/tests/main_tests/sparse_coding_test.cpp @@ -19,8 +19,8 @@ static const std::string testName = "SparseCoding"; #include #include "test_helper.hpp" -#include -#include "../test_tools.hpp" +#include "../catch.hpp" +#include "../test_catch_tools.hpp" using namespace mlpack; @@ -41,8 +41,6 @@ struct SparseCodingTestFixture } }; -BOOST_FIXTURE_TEST_SUITE(SparseCodingMainTest, SparseCodingTestFixture); - /** * Helper function to load datasets. */ @@ -50,18 +48,19 @@ void LoadData(arma::mat& inputData, arma::mat& testData) { // Load train dataset. if (!data::Load("iris_train.csv", inputData)) - BOOST_FAIL("Cannot load train dataset iris_train.csv!"); + FAIL("Cannot load train dataset iris_train.csv!"); // Load test dataset. if (!data::Load("iris_test.csv", testData)) - BOOST_FAIL("Cannot load test dataset iris_test.csv!"); + FAIL("Cannot load test dataset iris_test.csv!"); } /** * Make sure that output points in dictionary equals number of * atoms passed and codes have desired dimension. */ -BOOST_AUTO_TEST_CASE(SparseCodingOutputDimensionTest) +TEST_CASE_METHOD(SparseCodingTestFixture, "SparseCodingOutputDimensionTest", + "[SparseCodingMainTest][BindingTests]") { arma::mat inputData; arma::mat testData; @@ -78,25 +77,26 @@ BOOST_AUTO_TEST_CASE(SparseCodingOutputDimensionTest) mlpackMain(); // Check that number of output dictionary points are equals number of atoms. - BOOST_REQUIRE_EQUAL(IO::GetParam("dictionary").n_cols, 2); + REQUIRE(IO::GetParam("dictionary").n_cols == 2); // Check that number of output dictionary rows equal number of input rows // which equal 4 for each data point. - BOOST_REQUIRE_EQUAL(IO::GetParam("dictionary").n_rows, 4); + REQUIRE(IO::GetParam("dictionary").n_rows == 4); // Check that number of output points are equal to number of test points. // Test file contains 63 data points. - BOOST_REQUIRE_EQUAL(IO::GetParam("codes").n_cols, 63); + REQUIRE(IO::GetParam("codes").n_cols == 63); // Check that number of output codes rows equal number of atoms. - BOOST_REQUIRE_EQUAL(IO::GetParam("codes").n_rows, 2); + REQUIRE(IO::GetParam("codes").n_rows == 2); } /** * Ensure that training data is normalized if normalize * parameter is set to true. */ -BOOST_AUTO_TEST_CASE(SparseCodingNormalizationTest) +TEST_CASE_METHOD(SparseCodingTestFixture, "SparseCodingNormalizationTest", + "[SparseCodingMainTest][BindingTests]") { arma::mat inputData; arma::mat testData; @@ -155,11 +155,12 @@ BOOST_AUTO_TEST_CASE(SparseCodingNormalizationTest) * newton_tolerance value is always non-negative and number * of atoms is always positive. */ -BOOST_AUTO_TEST_CASE(SparseCodingBoundsTest) +TEST_CASE_METHOD(SparseCodingTestFixture, "SparseCodingBoundsTest", + "[SparseCodingMainTest][BindingTests]") { arma::mat inputData; if (!data::Load("iris_train.csv", inputData)) - BOOST_FAIL("Cannot load train dataset iris_train.csv!"); + FAIL("Cannot load train dataset iris_train.csv!"); // Test for L1 value. @@ -169,7 +170,7 @@ BOOST_AUTO_TEST_CASE(SparseCodingBoundsTest) SetInputParam("lambda1", (double) -1.0); Log::Fatal.ignoreInput = true; - BOOST_REQUIRE_THROW(mlpackMain(), std::runtime_error); + REQUIRE_THROWS_AS(mlpackMain(), std::runtime_error); Log::Fatal.ignoreInput = false; // Test for L2 value. @@ -181,7 +182,7 @@ BOOST_AUTO_TEST_CASE(SparseCodingBoundsTest) SetInputParam("lambda2", (double) -1.0); Log::Fatal.ignoreInput = true; - BOOST_REQUIRE_THROW(mlpackMain(), std::runtime_error); + REQUIRE_THROWS_AS(mlpackMain(), std::runtime_error); Log::Fatal.ignoreInput = false; // Test for max_iterations. @@ -193,7 +194,7 @@ BOOST_AUTO_TEST_CASE(SparseCodingBoundsTest) SetInputParam("max_iterations", (int) -1.0); Log::Fatal.ignoreInput = true; - BOOST_REQUIRE_THROW(mlpackMain(), std::runtime_error); + REQUIRE_THROWS_AS(mlpackMain(), std::runtime_error); Log::Fatal.ignoreInput = false; // Test for objective_tolerance. @@ -205,7 +206,7 @@ BOOST_AUTO_TEST_CASE(SparseCodingBoundsTest) SetInputParam("objective_tolerance", (double) -1.0); Log::Fatal.ignoreInput = true; - BOOST_REQUIRE_THROW(mlpackMain(), std::runtime_error); + REQUIRE_THROWS_AS(mlpackMain(), std::runtime_error); Log::Fatal.ignoreInput = false; // Test for newton_tolerance. @@ -217,7 +218,7 @@ BOOST_AUTO_TEST_CASE(SparseCodingBoundsTest) SetInputParam("newton_tolerance", (double) -1.0); Log::Fatal.ignoreInput = true; - BOOST_REQUIRE_THROW(mlpackMain(), std::runtime_error); + REQUIRE_THROWS_AS(mlpackMain(), std::runtime_error); Log::Fatal.ignoreInput = false; // Test for atoms. @@ -227,24 +228,25 @@ BOOST_AUTO_TEST_CASE(SparseCodingBoundsTest) SetInputParam("atoms", (int) 0); Log::Fatal.ignoreInput = true; - BOOST_REQUIRE_THROW(mlpackMain(), std::runtime_error); + REQUIRE_THROWS_AS(mlpackMain(), std::runtime_error); Log::Fatal.ignoreInput = false; } /** * Make sure atoms are specified if training data is passed. */ -BOOST_AUTO_TEST_CASE(SparseCodingReqAtomsTest) +TEST_CASE_METHOD(SparseCodingTestFixture, "SparseCodingReqAtomsTest", + "[SparseCodingMainTest][BindingTests]") { arma::mat inputData; if (!data::Load("iris_train.csv", inputData)) - BOOST_FAIL("Cannot load train dataset iris_train.csv!"); + FAIL("Cannot load train dataset iris_train.csv!"); // Input training data. SetInputParam("training", std::move(inputData)); Log::Fatal.ignoreInput = true; - BOOST_REQUIRE_THROW(mlpackMain(), std::runtime_error); + REQUIRE_THROWS_AS(mlpackMain(), std::runtime_error); Log::Fatal.ignoreInput = false; } @@ -252,7 +254,8 @@ BOOST_AUTO_TEST_CASE(SparseCodingReqAtomsTest) * Ensure only one of input_model or initial_dictionary * is specified. */ -BOOST_AUTO_TEST_CASE(SparseCodingModelVerTest) +TEST_CASE_METHOD(SparseCodingTestFixture, "SparseCodingModelVerTest", + "[SparseCodingMainTest][BindingTests]") { arma::mat inputData; arma::mat testData; @@ -266,7 +269,7 @@ BOOST_AUTO_TEST_CASE(SparseCodingModelVerTest) SetInputParam("initial_dictionary", std::move(initialDictionary)); Log::Fatal.ignoreInput = true; - BOOST_REQUIRE_THROW(mlpackMain(), std::runtime_error); + REQUIRE_THROWS_AS(mlpackMain(), std::runtime_error); Log::Fatal.ignoreInput = false; } @@ -274,7 +277,8 @@ BOOST_AUTO_TEST_CASE(SparseCodingModelVerTest) * Ensure that specified number of atoms and initial_dictionary * atoms are equal. */ -BOOST_AUTO_TEST_CASE(SparseCodingAtomsVerTest) +TEST_CASE_METHOD(SparseCodingTestFixture, "SparseCodingAtomsVerTest", + "[SparseCodingMainTest][BindingTests]") { arma::mat inputData; arma::mat testData; @@ -289,7 +293,7 @@ BOOST_AUTO_TEST_CASE(SparseCodingAtomsVerTest) SetInputParam("max_iterations", (int) 100); Log::Fatal.ignoreInput = true; - BOOST_REQUIRE_THROW(mlpackMain(), std::runtime_error); + REQUIRE_THROWS_AS(mlpackMain(), std::runtime_error); Log::Fatal.ignoreInput = false; } @@ -297,7 +301,8 @@ BOOST_AUTO_TEST_CASE(SparseCodingAtomsVerTest) * Ensure that input data and initial_dictionary * have same number of rows. */ -BOOST_AUTO_TEST_CASE(SparseCodingRowsVerTest) +TEST_CASE_METHOD(SparseCodingTestFixture, "SparseCodingRowsVerTest", + "[SparseCodingMainTest][BindingTests]") { arma::mat inputData; arma::mat testData; @@ -316,7 +321,7 @@ BOOST_AUTO_TEST_CASE(SparseCodingRowsVerTest) SetInputParam("normalize", (bool) true); Log::Fatal.ignoreInput = true; - BOOST_REQUIRE_THROW(mlpackMain(), std::runtime_error); + REQUIRE_THROWS_AS(mlpackMain(), std::runtime_error); Log::Fatal.ignoreInput = false; } @@ -324,7 +329,8 @@ BOOST_AUTO_TEST_CASE(SparseCodingRowsVerTest) * Ensure that training data and test data * have same dimensionality w.r.t rows. */ -BOOST_AUTO_TEST_CASE(SparseCodingDataDimensionalityTest) +TEST_CASE_METHOD(SparseCodingTestFixture, "SparseCodingDataDimensionalityTest", + "[SparseCodingMainTest][BindingTests]") { arma::mat inputData; arma::mat testData; @@ -342,14 +348,15 @@ BOOST_AUTO_TEST_CASE(SparseCodingDataDimensionalityTest) SetInputParam("test", std::move(testData)); Log::Fatal.ignoreInput = true; - BOOST_REQUIRE_THROW(mlpackMain(), std::runtime_error); + REQUIRE_THROWS_AS(mlpackMain(), std::runtime_error); Log::Fatal.ignoreInput = false; } /** * Check that saved model can be reused again. */ -BOOST_AUTO_TEST_CASE(SparseCodingModelReuseTest) +TEST_CASE_METHOD(SparseCodingTestFixture, "SparseCodingModelReuseTest", + "[SparseCodingMainTest][BindingTests]") { arma::mat inputData; arma::mat testData; @@ -384,18 +391,18 @@ BOOST_AUTO_TEST_CASE(SparseCodingModelReuseTest) mlpackMain(); // Check that number of output dictionary points are equals number of atoms. - BOOST_REQUIRE_EQUAL(IO::GetParam("dictionary").n_cols, 2); + REQUIRE(IO::GetParam("dictionary").n_cols == 2); // Check that number of output dictionary rows equal number of input rows // which equal 4 for each data point. - BOOST_REQUIRE_EQUAL(IO::GetParam("dictionary").n_rows, 4); + REQUIRE(IO::GetParam("dictionary").n_rows == 4); // Check that number of output points are equal to number of test points. // Test file contains 63 data points. - BOOST_REQUIRE_EQUAL(IO::GetParam("codes").n_cols, 63); + REQUIRE(IO::GetParam("codes").n_cols == 63); // Check that number of output codes rows equal number of atoms. - BOOST_REQUIRE_EQUAL(IO::GetParam("codes").n_rows, 2); + REQUIRE(IO::GetParam("codes").n_rows == 2); // Check that initial outputs and final outputs // using two models model are same. @@ -407,7 +414,8 @@ BOOST_AUTO_TEST_CASE(SparseCodingModelReuseTest) * Ensure that for different value of max iterations * outputs are different. */ -BOOST_AUTO_TEST_CASE(SparseCodingDiffMaxItrTest) +TEST_CASE_METHOD(SparseCodingTestFixture, "SparseCodingDiffMaxItrTest", + "[SparseCodingMainTest][BindingTests]") { arma::mat inputData; arma::mat testData; @@ -447,18 +455,19 @@ BOOST_AUTO_TEST_CASE(SparseCodingDiffMaxItrTest) // Check that initial outputs and final outputs // using two models model are different. - BOOST_REQUIRE_LT(arma::accu(dictionary == - IO::GetParam("dictionary")), dictionary.n_elem); + REQUIRE(arma::accu(dictionary == + IO::GetParam("dictionary")) < dictionary.n_elem); - BOOST_REQUIRE_LT(arma::accu(codes == - IO::GetParam("codes")), codes.n_elem); + REQUIRE(arma::accu(codes == + IO::GetParam("codes")) < codes.n_elem); } /** * Ensure that for different value of objective_tolerance * outputs are different. */ -BOOST_AUTO_TEST_CASE(SparseCodingDiffObjToleranceTest) +TEST_CASE_METHOD(SparseCodingTestFixture, "SparseCodingDiffObjToleranceTest", + "[SparseCodingMainTest][BindingTests]") { arma::mat inputData; arma::mat testData; @@ -495,18 +504,19 @@ BOOST_AUTO_TEST_CASE(SparseCodingDiffObjToleranceTest) // Check that initial outputs and final outputs // using two models model are different. - BOOST_REQUIRE_LT(arma::accu(dictionary == - IO::GetParam("dictionary")), dictionary.n_elem); - - BOOST_REQUIRE_LT(arma::accu(codes == - IO::GetParam("codes")), codes.n_elem); + REQUIRE(arma::accu(dictionary == + IO::GetParam("dictionary")) < dictionary.n_elem); + REQUIRE(arma::accu(codes == + IO::GetParam("codes")) < codes.n_elem); } /** * Ensure that for different value of newton_tolerance * outputs are different. */ -BOOST_AUTO_TEST_CASE(SparseCodingDiffNewtonToleranceTest) +TEST_CASE_METHOD(SparseCodingTestFixture, + "SparseCodingDiffNewtonToleranceTest", + "[SparseCodingMainTest][BindingTests]") { arma::mat inputData; arma::mat testData; @@ -543,18 +553,19 @@ BOOST_AUTO_TEST_CASE(SparseCodingDiffNewtonToleranceTest) // Check that initial outputs and final outputs // using two models model are different. - BOOST_REQUIRE_LT(arma::accu(dictionary == - IO::GetParam("dictionary")), dictionary.n_elem); + REQUIRE(arma::accu(dictionary == + IO::GetParam("dictionary")) < dictionary.n_elem); - BOOST_REQUIRE_LT(arma::accu(codes == - IO::GetParam("codes")), codes.n_elem); + REQUIRE(arma::accu(codes == + IO::GetParam("codes")) < codes.n_elem); } /** * Ensure that for different value of lambda1 * outputs are different. */ -BOOST_AUTO_TEST_CASE(SparseCodingDiffL1Test) +TEST_CASE_METHOD(SparseCodingTestFixture, "SparseCodingDiffL1Test", + "[SparseCodingMainTest][BindingTests]") { arma::mat inputData; arma::mat testData; @@ -591,18 +602,19 @@ BOOST_AUTO_TEST_CASE(SparseCodingDiffL1Test) // Check that initial outputs and final outputs // using two models model are different. - BOOST_REQUIRE_LT(arma::accu(dictionary == - IO::GetParam("dictionary")), dictionary.n_elem); + REQUIRE(arma::accu(dictionary == + IO::GetParam("dictionary")) < dictionary.n_elem); - BOOST_REQUIRE_LT(arma::accu(codes == - IO::GetParam("codes")), codes.n_elem); + REQUIRE(arma::accu(codes == + IO::GetParam("codes")) < codes.n_elem); } /** * Ensure that for different value of lambda2 * outputs are different. */ -BOOST_AUTO_TEST_CASE(SparseCodingDiffL2Test) +TEST_CASE_METHOD(SparseCodingTestFixture, "SparseCodingDiffL2Test", + "[SparseCodingMainTest][BindingTests]") { arma::mat inputData; arma::mat testData; @@ -639,18 +651,19 @@ BOOST_AUTO_TEST_CASE(SparseCodingDiffL2Test) // Check that initial outputs and final outputs // using two models model are different. - BOOST_REQUIRE_LT(arma::accu(dictionary == - IO::GetParam("dictionary")), dictionary.n_elem); + REQUIRE(arma::accu(dictionary == + IO::GetParam("dictionary")) < dictionary.n_elem); - BOOST_REQUIRE_LT(arma::accu(codes == - IO::GetParam("codes")), codes.n_elem); + REQUIRE(arma::accu(codes == + IO::GetParam("codes")) < codes.n_elem); } /** * Ensure that for different value of lambda1 & lambda2 * outputs are different. */ -BOOST_AUTO_TEST_CASE(SparseCodingDiffL1L2Test) +TEST_CASE_METHOD(SparseCodingTestFixture, "SparseCodingDiffL1L2Test", + "[SparseCodingMainTest][BindingTests]") { arma::mat inputData; arma::mat testData; @@ -689,11 +702,9 @@ BOOST_AUTO_TEST_CASE(SparseCodingDiffL1L2Test) // Check that initial outputs and final outputs // using two models model are different. - BOOST_REQUIRE_LT(arma::accu(dictionary == - IO::GetParam("dictionary")), dictionary.n_elem); + REQUIRE(arma::accu(dictionary == + IO::GetParam("dictionary")) < dictionary.n_elem); - BOOST_REQUIRE_LT(arma::accu(codes == - IO::GetParam("codes")), codes.n_elem); + REQUIRE(arma::accu(codes == + IO::GetParam("codes")) < codes.n_elem); } - -BOOST_AUTO_TEST_SUITE_END(); diff --git a/src/mlpack/tests/q_learning_test.cpp b/src/mlpack/tests/q_learning_test.cpp index 33ab7ea8a1..da7767ab3b 100644 --- a/src/mlpack/tests/q_learning_test.cpp +++ b/src/mlpack/tests/q_learning_test.cpp @@ -22,8 +22,9 @@ #include #include #include -#include #include +#include +#include #include #include #include @@ -515,7 +516,7 @@ BOOST_AUTO_TEST_CASE(PendulumWithSAC) for (size_t trial = 0; trial < 3; ++trial) { Log::Debug << "Trial number: " << trial << std::endl; - // Set up the policy and replay method. + // Set up the replay method. RandomReplay replayMethod(32, 10000); TrainingConfig config; @@ -547,4 +548,52 @@ BOOST_AUTO_TEST_CASE(PendulumWithSAC) BOOST_REQUIRE(converged); } +//! A test to ensure SAC works with multiple actions in action space. +BOOST_AUTO_TEST_CASE(SACForMultipleActions) +{ + ContinuousActionEnv::State::dimension = 3; + ContinuousActionEnv::Action::size = 4; + + FFN, GaussianInitialization> + policyNetwork(EmptyLoss<>(), GaussianInitialization(0, 0.1)); + policyNetwork.Add(new Linear<>(ContinuousActionEnv::State::dimension, 128)); + policyNetwork.Add(new ReLULayer<>()); + policyNetwork.Add(new Linear<>(128, ContinuousActionEnv::Action::size)); + policyNetwork.Add(new TanHLayer<>()); + + FFN, GaussianInitialization> + qNetwork(EmptyLoss<>(), GaussianInitialization(0, 0.1)); + qNetwork.Add(new Linear<>(ContinuousActionEnv::State::dimension + + ContinuousActionEnv::Action::size, 128)); + qNetwork.Add(new ReLULayer<>()); + qNetwork.Add(new Linear<>(128, 1)); + + // Set up the replay method. + RandomReplay replayMethod(32, 10000); + + TrainingConfig config; + config.StepSize() = 0.001; + config.TargetNetworkSyncInterval() = 1; + config.UpdateInterval() = 3; + + // Set up Soft actor-critic agent. + SAC + agent(config, qNetwork, policyNetwork, replayMethod); + + agent.State().Data() = arma::randu + (ContinuousActionEnv::State::dimension, 1); + agent.SelectAction(); + + // Test to check if the action dimension given by the agent is correct. + BOOST_REQUIRE_EQUAL(agent.Action().action.size(), + ContinuousActionEnv::Action::size); + + replayMethod.Store(agent.State(), agent.Action(), 1, agent.State(), 1, 0.99); + agent.TotalSteps()++; + agent.Update(); + // If the agent is able to reach till this point of the test, it is assured + // that the agent can handle multiple actions in continuous space. +} + BOOST_AUTO_TEST_SUITE_END(); diff --git a/src/mlpack/tests/rbm_network_test.cpp b/src/mlpack/tests/rbm_network_test.cpp index 0cf8ff2316..820f9616f5 100644 --- a/src/mlpack/tests/rbm_network_test.cpp +++ b/src/mlpack/tests/rbm_network_test.cpp @@ -88,14 +88,13 @@ BOOST_AUTO_TEST_CASE(BinaryRBMClassificationTest) for (size_t i = 0; i < trainData.n_cols; ++i) { - model.HiddenMean(std::move(trainData.col(i)), std::move(output)); + model.HiddenMean(trainData.col(i), output); XRbm.col(i) = output; } for (size_t i = 0; i < testData.n_cols; ++i) { - model.HiddenMean(std::move(testData.col(i)), - std::move(output)); + model.HiddenMean(testData.col(i), output); YRbm.col(i) = output; } const size_t numClasses = 10; // Number of classes. @@ -189,15 +188,13 @@ BOOST_AUTO_TEST_CASE(ssRBMClassificationTest) for (size_t i = 0; i < trainData.n_cols; ++i) { - modelssRBM.HiddenMean(std::move(trainData.col(i)), - std::move(output)); + modelssRBM.HiddenMean(trainData.col(i), output); XRbm.col(i) = output; } for (size_t i = 0; i < testData.n_cols; ++i) { - modelssRBM.HiddenMean(std::move(testData.col(i)), - std::move(output)); + modelssRBM.HiddenMean(testData.col(i), output); YRbm.col(i) = output; } const size_t numClasses = 10; // Number of classes. @@ -238,7 +235,7 @@ void BuildVanillaNetwork(MatType& trainData, arma::vec calculatedFreeEnergy(4, arma::fill::zeros); for (size_t i = 0; i < trainData.n_cols; ++i) { - calculatedFreeEnergy(i) = model.FreeEnergy(std::move(trainData.col(i))); + calculatedFreeEnergy(i) = model.FreeEnergy(trainData.col(i)); } for (size_t i = 0; i < freeEnergy.n_elem; ++i) diff --git a/src/mlpack/tests/sparse_autoencoder_test.cpp b/src/mlpack/tests/sparse_autoencoder_test.cpp index 03e95f8534..feb65271d6 100644 --- a/src/mlpack/tests/sparse_autoencoder_test.cpp +++ b/src/mlpack/tests/sparse_autoencoder_test.cpp @@ -12,15 +12,13 @@ #include #include -#include -#include "test_tools.hpp" +#include "catch.hpp" +#include "test_catch_tools.hpp" using namespace mlpack; using namespace mlpack::nn; -BOOST_AUTO_TEST_SUITE(SparseAutoencoderTest); - -BOOST_AUTO_TEST_CASE(SparseAutoencoderFunctionEvaluate) +TEST_CASE("SparseAutoencoderFunctionEvaluate", "[SparseAutoencoderTest]") { const size_t vSize = 5; const size_t hSize = 3; @@ -41,21 +39,27 @@ BOOST_AUTO_TEST_CASE(SparseAutoencoderFunctionEvaluate) SparseAutoencoderFunction saf1(data1, vSize, hSize, 0, 0); // Test using first dataset. Values were calculated using Octave. - BOOST_REQUIRE_CLOSE(saf1.Evaluate(arma::ones(r, c)), 1.190472606540, 1e-5); - BOOST_REQUIRE_CLOSE(saf1.Evaluate(arma::zeros(r, c)), 0.150000000000, 1e-5); - BOOST_REQUIRE_CLOSE(saf1.Evaluate(-arma::ones(r, c)), 0.048800332266, 1e-5); + REQUIRE(saf1.Evaluate(arma::ones(r, c)) == + Approx(1.190472606540).epsilon(1e-7)); + REQUIRE(saf1.Evaluate(arma::zeros(r, c)) == + Approx(0.150000000000).epsilon(1e-7)); + REQUIRE(saf1.Evaluate(-arma::ones(r, c)) == + Approx(0.048800332266).epsilon(1e-7)); // Create a SparseAutoencoderFunction. Regularization and KL divergence terms // ignored. SparseAutoencoderFunction saf2(data2, vSize, hSize, 0, 0); // Test using second dataset. Values were calculated using Octave. - BOOST_REQUIRE_CLOSE(saf2.Evaluate(arma::ones(r, c)), 1.197585812647, 1e-5); - BOOST_REQUIRE_CLOSE(saf2.Evaluate(arma::zeros(r, c)), 0.150000000000, 1e-5); - BOOST_REQUIRE_CLOSE(saf2.Evaluate(-arma::ones(r, c)), 0.063466617408, 1e-5); + REQUIRE(saf2.Evaluate(arma::ones(r, c)) == + Approx(1.197585812647).epsilon(1e-7)); + REQUIRE(saf2.Evaluate(arma::zeros(r, c)) == + Approx(0.150000000000).epsilon(1e-7)); + REQUIRE(saf2.Evaluate(-arma::ones(r, c)) == + Approx(0.063466617408).epsilon(1e-7)); } -BOOST_AUTO_TEST_CASE(SparseAutoencoderFunctionRandomEvaluate) +TEST_CASE("SparseAutoencoderFunctionRandomEvaluate", "[SparseAutoencoderTest]") { const size_t points = 1000; const size_t trials = 50; @@ -100,11 +104,13 @@ BOOST_AUTO_TEST_CASE(SparseAutoencoderFunctionRandomEvaluate) reconstructionError /= points; // Compare with the value returned by the function. - BOOST_REQUIRE_CLOSE(saf.Evaluate(parameters), reconstructionError, 1e-5); + REQUIRE(saf.Evaluate(parameters) == + Approx(reconstructionError).epsilon(1e-7)); } } -BOOST_AUTO_TEST_CASE(SparseAutoencoderFunctionRegularizationEvaluate) +TEST_CASE("SparseAutoencoderFunctionRegularizationEvaluate", + "[SparseAutoencoderTest]") { const size_t points = 1000; const size_t trials = 50; @@ -138,14 +144,15 @@ BOOST_AUTO_TEST_CASE(SparseAutoencoderFunctionRegularizationEvaluate) const double smallRegTerm = 0.25 * wL2SquaredNorm; const double bigRegTerm = 10 * wL2SquaredNorm; - BOOST_REQUIRE_CLOSE(safNoReg.Evaluate(parameters) + smallRegTerm, - safSmallReg.Evaluate(parameters), 1e-5); - BOOST_REQUIRE_CLOSE(safNoReg.Evaluate(parameters) + bigRegTerm, - safBigReg.Evaluate(parameters), 1e-5); + REQUIRE(safNoReg.Evaluate(parameters) + smallRegTerm == + Approx(safSmallReg.Evaluate(parameters)).epsilon(1e-7)); + REQUIRE(safNoReg.Evaluate(parameters) + bigRegTerm == + Approx(safBigReg.Evaluate(parameters)).epsilon(1e-7)); } } -BOOST_AUTO_TEST_CASE(SparseAutoencoderFunctionKLDivergenceEvaluate) +TEST_CASE("SparseAutoencoderFunctionKLDivergenceEvaluate", + "[SparseAutoencoderTest]") { const size_t points = 1000; const size_t trials = 50; @@ -194,14 +201,14 @@ BOOST_AUTO_TEST_CASE(SparseAutoencoderFunctionKLDivergenceEvaluate) const double bigDivTerm = 20 * arma::accu(rho * arma::log(rho / rhoCap) + (1 - rho) * arma::log((1 - rho) / (1 - rhoCap))); - BOOST_REQUIRE_CLOSE(safNoDiv.Evaluate(parameters) + smallDivTerm, - safSmallDiv.Evaluate(parameters), 1e-5); - BOOST_REQUIRE_CLOSE(safNoDiv.Evaluate(parameters) + bigDivTerm, - safBigDiv.Evaluate(parameters), 1e-5); + REQUIRE(safNoDiv.Evaluate(parameters) + smallDivTerm == + Approx(safSmallDiv.Evaluate(parameters)).epsilon(1e-7)); + REQUIRE(safNoDiv.Evaluate(parameters) + bigDivTerm == + Approx(safBigDiv.Evaluate(parameters)).epsilon(1e-7)); } } -BOOST_AUTO_TEST_CASE(SparseAutoencoderFunctionGradient) +TEST_CASE("SparseAutoencoderFunctionGradient", "[SparseAutoencoderTest]") { const size_t points = 1000; const size_t vSize = 20; @@ -261,11 +268,9 @@ BOOST_AUTO_TEST_CASE(SparseAutoencoderFunctionGradient) parameters(i, j) += epsilon; // Compare numerical and backpropagation gradient values. - BOOST_REQUIRE_CLOSE(numGradient1, gradient1(i, j), 1e-2); - BOOST_REQUIRE_CLOSE(numGradient2, gradient2(i, j), 1e-2); - BOOST_REQUIRE_CLOSE(numGradient3, gradient3(i, j), 1e-2); + REQUIRE(numGradient1 == Approx(gradient1(i, j)).epsilon(1e-4)); + REQUIRE(numGradient2 == Approx(gradient2(i, j)).epsilon(1e-4)); + REQUIRE(numGradient3 == Approx(gradient3(i, j)).epsilon(1e-4)); } } } - -BOOST_AUTO_TEST_SUITE_END(); diff --git a/src/mlpack/tests/sparse_coding_test.cpp b/src/mlpack/tests/sparse_coding_test.cpp index 513db86c85..81724ceeba 100644 --- a/src/mlpack/tests/sparse_coding_test.cpp +++ b/src/mlpack/tests/sparse_coding_test.cpp @@ -15,17 +15,15 @@ #include #include -#include -#include "test_tools.hpp" -#include "serialization.hpp" +#include "catch.hpp" +#include "test_catch_tools.hpp" +#include "serialization_catch.hpp" using namespace arma; using namespace mlpack; using namespace mlpack::regression; using namespace mlpack::sparse_coding; -BOOST_AUTO_TEST_SUITE(SparseCodingTest); - void SCVerifyCorrectness(vec beta, vec errCorr, double lambda) { const double tol = 1e-12; @@ -35,22 +33,23 @@ void SCVerifyCorrectness(vec beta, vec errCorr, double lambda) if (beta(j) == 0) { // Make sure that errCorr(j) <= lambda. - BOOST_REQUIRE_SMALL(std::max(fabs(errCorr(j)) - lambda, 0.0), tol); + REQUIRE(std::max(fabs(errCorr(j)) - lambda, 0.0) == + Approx(0.0).margin(tol)); } else if (beta(j) < 0) { // Make sure that errCorr(j) == lambda. - BOOST_REQUIRE_SMALL(errCorr(j) - lambda, tol); + REQUIRE(errCorr(j) - lambda == Approx(0.0).margin(tol)); } else // beta(j) > 0. { // Make sure that errCorr(j) == -lambda. - BOOST_REQUIRE_SMALL(errCorr(j) + lambda, tol); + REQUIRE(errCorr(j) + lambda == Approx(0.0).margin(tol)); } } } -BOOST_AUTO_TEST_CASE(SparseCodingTestCodingStepLasso) +TEST_CASE("SparseCodingTestCodingStepLasso", "[SparseCodingTest]") { double lambda1 = 0.1; uword nAtoms = 25; @@ -79,7 +78,7 @@ BOOST_AUTO_TEST_CASE(SparseCodingTestCodingStepLasso) } } -BOOST_AUTO_TEST_CASE(SparseCodingTestCodingStepElasticNet) +TEST_CASE("SparseCodingTestCodingStepElasticNet", "[SparseCodingTest]") { double lambda1 = 0.1; double lambda2 = 0.2; @@ -110,7 +109,7 @@ BOOST_AUTO_TEST_CASE(SparseCodingTestCodingStepElasticNet) } } -BOOST_AUTO_TEST_CASE(SparseCodingTestDictionaryStep) +TEST_CASE("SparseCodingTestDictionaryStep", "[SparseCodingTest]") { const double tol = 1e-6; @@ -135,10 +134,10 @@ BOOST_AUTO_TEST_CASE(SparseCodingTestDictionaryStep) uvec adjacencies = find(Z); double normGradient = sc.OptimizeDictionary(X, Z, adjacencies); - BOOST_REQUIRE_SMALL(normGradient, tol); + REQUIRE(normGradient == Approx(0.0).margin(tol)); } -BOOST_AUTO_TEST_CASE(SerializationTest) +TEST_CASE("SerializationTest", "[SparseCodingTest]") { mat X = randu(100, 100); size_t nAtoms = 25; @@ -164,35 +163,38 @@ BOOST_AUTO_TEST_CASE(SerializationTest) CheckMatrices(codes, xmlCodes, textCodes, binaryCodes); // Check the parameters, too. - BOOST_REQUIRE_EQUAL(sc.Atoms(), scXml.Atoms()); - BOOST_REQUIRE_EQUAL(sc.Atoms(), scText.Atoms()); - BOOST_REQUIRE_EQUAL(sc.Atoms(), scBinary.Atoms()); + REQUIRE(sc.Atoms() == scXml.Atoms()); + REQUIRE(sc.Atoms() == scText.Atoms()); + REQUIRE(sc.Atoms() == scBinary.Atoms()); - BOOST_REQUIRE_CLOSE(sc.Lambda1(), scXml.Lambda1(), 1e-5); - BOOST_REQUIRE_CLOSE(sc.Lambda1(), scText.Lambda1(), 1e-5); - BOOST_REQUIRE_CLOSE(sc.Lambda1(), scBinary.Lambda1(), 1e-5); + REQUIRE(sc.Lambda1() == Approx(scXml.Lambda1()).epsilon(1e-7)); + REQUIRE(sc.Lambda1() == Approx(scText.Lambda1()).epsilon(1e-7)); + REQUIRE(sc.Lambda1() == Approx(scBinary.Lambda1()).epsilon(1e-7)); - BOOST_REQUIRE_CLOSE(sc.Lambda2(), scXml.Lambda2(), 1e-5); - BOOST_REQUIRE_CLOSE(sc.Lambda2(), scText.Lambda2(), 1e-5); - BOOST_REQUIRE_CLOSE(sc.Lambda2(), scBinary.Lambda2(), 1e-5); + REQUIRE(sc.Lambda2() == Approx(scXml.Lambda2()).epsilon(1e-7)); + REQUIRE(sc.Lambda2() == Approx(scText.Lambda2()).epsilon(1e-7)); + REQUIRE(sc.Lambda2() == Approx(scBinary.Lambda2()).epsilon(1e-7)); - BOOST_REQUIRE_EQUAL(sc.MaxIterations(), scXml.MaxIterations()); - BOOST_REQUIRE_EQUAL(sc.MaxIterations(), scText.MaxIterations()); - BOOST_REQUIRE_EQUAL(sc.MaxIterations(), scBinary.MaxIterations()); + REQUIRE(sc.MaxIterations() == scXml.MaxIterations()); + REQUIRE(sc.MaxIterations() == scText.MaxIterations()); + REQUIRE(sc.MaxIterations() == scBinary.MaxIterations()); - BOOST_REQUIRE_CLOSE(sc.ObjTolerance(), scXml.ObjTolerance(), 1e-5); - BOOST_REQUIRE_CLOSE(sc.ObjTolerance(), scText.ObjTolerance(), 1e-5); - BOOST_REQUIRE_CLOSE(sc.ObjTolerance(), scBinary.ObjTolerance(), 1e-5); + REQUIRE(sc.ObjTolerance() == Approx(scXml.ObjTolerance()).epsilon(1e-7)); + REQUIRE(sc.ObjTolerance() == Approx(scText.ObjTolerance()).epsilon(1e-7)); + REQUIRE(sc.ObjTolerance() == Approx(scBinary.ObjTolerance()).epsilon(1e-7)); - BOOST_REQUIRE_CLOSE(sc.NewtonTolerance(), scXml.NewtonTolerance(), 1e-5); - BOOST_REQUIRE_CLOSE(sc.NewtonTolerance(), scText.NewtonTolerance(), 1e-5); - BOOST_REQUIRE_CLOSE(sc.NewtonTolerance(), scBinary.NewtonTolerance(), 1e-5); + REQUIRE(sc.NewtonTolerance() == + Approx(scXml.NewtonTolerance()).epsilon(1e-7)); + REQUIRE(sc.NewtonTolerance() == + Approx(scText.NewtonTolerance()).epsilon(1e-7)); + REQUIRE(sc.NewtonTolerance() == + Approx(scBinary.NewtonTolerance()).epsilon(1e-7)); } /** * Test that SparseCoding::Train() returns finite final objective value. */ -BOOST_AUTO_TEST_CASE(SparseCodingTrainReturnObjective) +TEST_CASE("SparseCodingTrainReturnObjective", "[SparseCodingTest]") { const double tol = 1e-6; @@ -210,7 +212,5 @@ BOOST_AUTO_TEST_CASE(SparseCodingTrainReturnObjective) SparseCoding sc(nAtoms, lambda1, 0.0, 0, 0.01, tol); double objVal = sc.Train(X); - BOOST_REQUIRE_EQUAL(std::isfinite(objVal), true); + REQUIRE(std::isfinite(objVal) == true); } - -BOOST_AUTO_TEST_SUITE_END();