diff --git a/README.md b/README.md index b392b277dd..c6e02bf0be 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,7 @@ programs, Python bindings, Julia bindings, Go bindings and R bindings. - [mlpack homepage](https://www.mlpack.org/) - [mlpack documentation](https://www.mlpack.org/doc/index.html) - [Examples repository](https://github.com/mlpack/examples/) - - [Tutorials](doc/tutorials/README.md) + - [Tutorials](doc/user/tutorials.md) - [Development Site (Github)](https://github.com/mlpack/mlpack/) [//]: # (numfocus-fiscal-sponsor-attribution) @@ -69,13 +69,9 @@ variety of other needs. 1. [Citation details](#1-citation-details) 2. [Dependencies](#2-dependencies) - 3. [Installing and using mlpack in C++](#3-installing-and-using-mlpack-in-c) - 4. [Building mlpack bindings to other languages](#4-building-mlpack-bindings-to-other-languages) - 1. [Command-line programs](#4i-command-line-programs) - 2. [Python bindings](#4ii-python-bindings) - 3. [R bindings](#4iii-r-bindings) - 4. [Julia bindings](#4iv-julia-bindings) - 5. [Go bindings](#4v-go-bindings) + 3. [Installation](#3-installation) + 4. [Usage from C++](#4-usage-from-c) + 1. [Reducing compile time](#41-reducing-compile-time) 5. [Building mlpack's test suite](#5-building-mlpacks-test-suite) 6. [Further resources](#6-further-resources) @@ -107,6 +103,7 @@ Citations are beneficial for the growth and improvement of mlpack. ## 2. Dependencies **mlpack** requires the following additional dependencies: + - C++17 compiler - [Armadillo](https://arma.sourceforge.net)   >= 10.8 - [ensmallen](https://ensmallen.org)  >= 2.10.0 @@ -117,57 +114,12 @@ available. If you are compiling Armadillo by hand, ensure that LAPACK and BLAS are enabled. -## 3. Installing and using mlpack in C++ +## 3. Installation -*See also the [C++ quickstart](doc/quickstart/cpp.md).* +Detailed installation instructions can be found on the +[Installing mlpack](doc/user/install.md) page. -Since mlpack is a header-only library, installing just the headers for use in a -C++ application is trivial. - -From the root of the sources, configure and install -in the standard CMake way: - -```sh -mkdir build && cd build/ -cmake .. -sudo make install -``` - -If the `cmake ..` command fails due to unavailable dependencies, consider either using the -`-DDOWNLOAD_DEPENDENCIES=ON` option as detailed in [the following -subsection](#31-additional-build-options), or ensure that mlpack's dependencies -are installed, e.g. using the system package manager. For example, on Debian -and Ubuntu, all relevant dependencies can be installed with `sudo apt-get -install libarmadillo-dev libensmallen-dev libcereal-dev libstb-dev g++ cmake`. - -Alternatively, since CMake v3.14.0 the `cmake` command can create the build -folder itself, and so the above commands can be rewritten as follows: - -```sh -cmake -S . -B build -sudo cmake --build build --target install -``` - -During configuration, CMake adjusts the file `mlpack/config.hpp` using the -details of the local system. This file can be modified by hand as necessary -before or after installation. - -### 3.1. Additional build options - -You can add a few arguments to the `cmake` command to control the behavior of -the configuration and build process. Simply add these to the `cmake` command. -Some options are given below: - - - `-DDOWNLOAD_DEPENDENCIES=ON` will automatically download mlpack's - dependencies (ensmallen, Armadillo, and cereal). Installing Armadillo this - way is not recommended and it is better to use your system package manager - when possible (see [below](#31a-linking-with-autodownloaded-armadillo)). - - `-DCMAKE_INSTALL_PREFIX=/install/root/` will set the root of the install - directory to `/install/root` when `make install` is run. - - `-DDEBUG=ON` will enable debugging symbols in any compiled bindings or tests. - -There are also options to enable building bindings to each language that mlpack -supports; those are detailed in the following sections. +## 4. Usage from C++ Once headers are installed with `make install`, using mlpack in an application consists only of including it. So, your program should include mlpack: @@ -189,44 +141,19 @@ add `#define MLPACK_ENABLE_ANN_SERIALIZATION` before including ``. If you don't define `MLPACK_ENABLE_ANN_SERIALIZATION` and your code serializes a neural network, a compilation error will occur. -See the [C++ quickstart](doc/quickstart/cpp.md) and the -[examples](https://github.com/mlpack/examples) repository for some examples -of mlpack applications in C++, with corresponding `Makefile`s. +See also: -#### 3.1.a. Linking with autodownloaded Armadillo + * the [test program compilation section](doc/user/install.md#compiling-a-test-program) + of the installation documentation, + * the [C++ quickstart](doc/quickstart/cpp.md), and + * the [examples repository](https://github.com/mlpack/examples) repository for + some examples of mlpack applications in C++, with corresponding `Makefile`s. -When the autodownloader is used to download Armadillo -(`-DDOWNLOAD_DEPENDENCIES=ON`), the Armadillo runtime library is not built and -Armadillo must be used in header-only mode. The autodownloader also does not -download dependencies of Armadillo such as OpenBLAS. For this reason, it is -recommended to instead install Armadillo using your system package manager, -which will also install the dependencies of Armadillo. For example, on Ubuntu -and Debian systems, Armadillo can be installed with - -```sh -sudo apt-get install libarmadillo-dev -``` - -and other package managers such as `dnf` and `brew` and `pacman` also have -Armadillo packages available. - -If the autodownloader is used to provide Armadillo, mlpack programs cannot be -linked with `-larmadillo`. Instead, you must link directly with the -dependencies of Armadillo. For example, on a system that has OpenBLAS -available, compilation can be done like this: - -```sh -g++ -O3 -std=c++17 -o my_program my_program.cpp -lopenblas -fopenmp -``` - -See [the Armadillo documentation](https://arma.sourceforge.net/faq.html#linking) -for more information on linking Armadillo programs. - -### 3.2. Reducing compile time +### 4.1. Reducing compile time mlpack is a template-heavy library, and if care is not used, compilation time of -a project can be increased greatly. Fortunately, there are a number of ways to -reduce compilation time: +a project can be very high. Fortunately, there are a number of ways to reduce +compilation time: * Include individual headers, like ``, if you are only using one component, instead of ``. This reduces the @@ -248,241 +175,15 @@ reduce compilation time: Other strategies exist too, such as precompiled headers, compiler options, [`ccache`](https://ccache.dev), and others. -## 4. Building mlpack bindings to other languages - -mlpack is not just a header-only library: it also comes with bindings to a -number of other languages, this allows flexible use of mlpack's efficient -implementations from languages that aren't C++. - -In general, you should *not* need to build these by hand---they should be -provided by either your system package manager or your language's package -manager. - -Building the bindings for a particular language is done by calling `cmake` with -different options; each example below shows how to configure an individual set -of bindings, but it is of course possible to combine the options and build -bindings for many languages at once. - -### 4.i. Command-line programs - -*See also the [command-line quickstart](doc/quickstart/cli.md).* - -The command-line programs have no extra dependencies. The set of programs that -will be compiled is detailed and documented on the [command-line program -documentation page](doc/user/bindings/cli.md). - -From the root of the mlpack sources, run the following commands to build and -install the command-line bindings: - -```sh -mkdir build && cd build/ -cmake -DBUILD_CLI_PROGRAMS=ON ../ -make -sudo make install -``` - -You can use `make -j`, where `N` is the number of cores on your machine, to -build in parallel; e.g., `make -j4` will use 4 cores to build. - -### 4.ii. Python bindings - -*See also the [Python quickstart](doc/quickstart/python.md).* - -mlpack's Python bindings are available on -[PyPI](https://pypi.org/project/mlpack/) and -[conda-forge](https://anaconda.org/conda-forge/mlpack), and can be installed -with either `pip install mlpack` or `conda install -c conda-forge mlpack`. -These sources are recommended, as building the Python bindings by hand can be -complex. - -With that in mind, if you would still like to manually build the mlpack Python -bindings, first make sure that the following Python packages are installed: - - - setuptools - - wheel - - cython >= 0.24 - - numpy - - pandas >= 0.15.0 - -Now, from the root of the mlpack sources, run the following commands to build -and install the Python bindings: - -```sh -mkdir build && cd build/ -cmake -DBUILD_PYTHON_BINDINGS=ON ../ -make -sudo make install -``` - -You can use `make -j`, where `N` is the number of cores on your machine, to -build in parallel; e.g., `make -j4` will use 4 cores to build. You can also -specify a custom Python interpreter with the CMake option -`-DPYTHON_EXECUTABLE=/path/to/python`. - -### 4.iii. R bindings - -*See also the [R quickstart](doc/quickstart/r.md).* - -mlpack's R bindings are available as the R package -[mlpack](https://cran.r-project.org/web/packages/mlpack/index.html) on CRAN. -You can install the package by running `install.packages('mlpack')`, and this is -the recommended way of getting mlpack in R. - -If you still wish to build the R bindings by hand, first make sure the following -dependencies are installed: - - - R >= 4.0 - - Rcpp >= 0.12.12 - - RcppArmadillo >= 0.10.8.0 - - RcppEnsmallen >= 0.2.10.0 - - roxygen2 - - testthat - - pkgbuild - -These can be installed with `install.packages()` inside of your R environment. -Once the dependencies are available, you can configure mlpack and build the R -bindings by running the following commands from the root of the mlpack sources: - -```sh -mkdir build && cd build/ -cmake -DBUILD_R_BINDINGS=ON ../ -make -sudo make install -``` - -You may need to specify the location of the R program in the `cmake` command -with the option `-DR_EXECUTABLE=/path/to/R`. - -Once the build is complete, a tarball can be found under the build directory in -`src/mlpack/bindings/R/`, and then that can be installed into your R environment -with a command like `install.packages(mlpack_3.4.3.tar.gz, repos=NULL, -type='source')`. - -### 4.iv. Julia bindings - -*See also the [Julia quickstart](doc/quickstart/julia.md).* - -mlpack's Julia bindings are available by installing the -[mlpack.jl](https://github.com/mlpack/mlpack.jl) package using -`Pkg.add("mlpack.jl")`. The process of building, packaging, and distributing -mlpack's Julia bindings is very nontrivial, so it is recommended to simply use -the version available in `Pkg`, but if you want to build the bindings by hand -anyway, you can configure and build them by running the following commands from -the root of the mlpack sources: - -```sh -mkdir build && cd build/ -cmake -DBUILD_JULIA_BINDINGS=ON ../ -make -``` - -If CMake cannot find your Julia installation, you can add -`-DJULIA_EXECUTABLE=/path/to/julia` to the CMake configuration step. - -Note that the `make install` step is not done above, since the Julia binding -build system was not meant to be installed directly. Instead, to use handbuilt -bindings (for instance, to test them), one option is to start Julia with -`JULIA_PROJECT` set as an environment variable: - -```sh -cd build/src/mlpack/bindings/julia/mlpack/ -JULIA_PROJECT=$PWD julia -``` - -and then `using mlpack` should work. - -### 4.v. Go bindings - -*See also the [Go quickstart](doc/quickstart/go.md).* - -To build mlpack's Go bindings, ensure that Go >= 1.11.0 is installed, and that -the Gonum package is available. You can use `go get` to install mlpack as a -module in a Go project: - -```sh -go get -u mlpack.org/v1/mlpack -``` - -The Go bindings themselves will then need to be compiled. Find the mlpack -directory under `$GOMODCACHE/mlpack.org/v1/mlpack` and run these commands: - -```sh -make -sudo make install -``` - -Then, `go run my_code.go` will be able to correctly link against mlpack's Go -bindings and run. - -The process of building the Go bindings by hand is a little tedious, so -following the steps above is recommended. However, if you wish to build the Go -bindings by hand anyway, you can do this by running the following commands from -the root of the mlpack sources: - -```sh -mkdir build && cd build/ -cmake -DBUILD_GO_BINDINGS=ON ../ -make -sudo make install -``` - ## 5. Building mlpack's test suite -mlpack contains an extensive test suite that exercises every part of the -codebase. It is easy to build and run the tests with CMake and CTest, as below: - -```sh -mkdir build && cd build/ -cmake -DBUILD_TESTS=ON ../ -make -ctest . -``` - -If you want to test the bindings, too, you will have to adapt the CMake -configuration command to turn on the language bindings that you want to -test---see the previous sections for details. +See the [installation instruction section](doc/user/install.md#build-tests). ## 6. Further Resources More documentation is available for both users and developers. -***User documentation***: - - - [Matrices in mlpack](doc/user/matrices.md) - - [Loading and saving mlpack objects](doc/user/load_save.md) - - [Cross-Validation](doc/user/cv.md) - - [Hyper-parameter Tuning](doc/user/hpt.md) - - [Building mlpack from source on Windows](doc/user/build_windows.md) - - [Sample C++ ML App for Windows](doc/user/sample_ml_app.md) - - [mlpack core library documentation](doc/user/core.md) - - [Examples repository](https://github.com/mlpack/examples/) - -***Tutorials:*** - - - [Alternating Matrix Factorization (AMF)](doc/tutorials/amf.md) - - [Artificial Neural Networks (ANN)](doc/tutorials/ann.md) - - [Approximate k-Furthest Neighbor Search (`approx_kfn`)](doc/tutorials/approx_kfn.md) - - [Collaborative Filtering (CF)](doc/tutorials/cf.md) - - [DatasetMapper](doc/tutorials/datasetmapper.md) - - [Density Estimation Trees (DET)](doc/tutorials/det.md) - - [Euclidean Minimum Spanning Trees (EMST)](doc/tutorials/emst.md) - - [Fast Max-Kernel Search (FastMKS)](doc/tutorials/fastmks.md) - - [Image Utilities](doc/tutorials/image.md) - - [k-Means Clustering](doc/tutorials/kmeans.md) - - [Linear Regression](doc/tutorials/linear_regression.md) - - [Neighbor Search (k-Nearest-Neighbors)](doc/tutorials/neighbor_search.md) - - [Range Search](doc/tutorials/range_search.md) - - [Reinforcement Learning](doc/tutorials/reinforcement_learning.md) - -***Developer documentation***: - - - [Writing an mlpack binding](doc/developer/iodoc.md) - - [mlpack Timers](doc/developer/timer.md) - - [mlpack automatic bindings to other languages](doc/developer/bindings.md) - - [The ElemType policy in mlpack](doc/developer/elemtype.md) - - [The KernelType policy in mlpack](doc/developer/kernels.md) - - [The DistanceType policy in mlpack](doc/developer/distances.md) - - [The TreeType policy in mlpack](doc/developer/trees.md) + * [Documentation homepage](https://www.mlpack.org/doc/index.html) To learn about the development goals of mlpack in the short- and medium-term future, see the [vision document](https://www.mlpack.org/papers/vision.pdf). diff --git a/doc/citation.md b/doc/citation.md index fc23af8746..6da71182df 100644 --- a/doc/citation.md +++ b/doc/citation.md @@ -43,7 +43,7 @@ internal design. library](https://joss.theoj.org/papers/10.21105/joss.00726) (2018) * [mlpack open-source machine learning library and - community](http://kurg.org/pub/pdf/2018mlossmlpack.pdf) (2018) + community](https://openreview.net/pdf?id=rJxx0Y6NhX) (2018) * [Designing and building the mlpack open-source machine learning library](https://arxiv.org/abs/1708.05279) (2017) diff --git a/doc/css/gfm-mod.css b/doc/css/gfm-mod.css index 17ab82a61c..2a370bd9c8 100644 --- a/doc/css/gfm-mod.css +++ b/doc/css/gfm-mod.css @@ -21,8 +21,8 @@ body { div#content { padding-top: 10px; padding-bottom: 10px; - padding: 30px; - max-width: 920px; + padding: 10px; + max-width: 880px; margin: auto; } @@ -1060,9 +1060,9 @@ div#sidebar { float: left; position: fixed; top: 55px; - min-width: calc(50% - 460px); + min-width: calc(50% - 450px); font-size: 90%; - max-width: calc(50% - 460px); + max-width: calc(50% - 450px); overflow-y: scroll; bottom: 0; } @@ -1071,7 +1071,7 @@ div#sidebar ul { border-top: 2px solid #ccc; padding: 0.5em; list-style-type: none; - padding-left: 0.5em; + padding-right: 0em; margin-bottom: 0px; } @@ -1120,6 +1120,17 @@ div#sidebar details[open] details[open] summary::after { content: " [-]"; } +div#sidebar details[open] details[open] details summary::after { + content: " [+]"; +} + +div#sidebar details[open] details[open] details[open] summary::after { + content: " [-]"; +} + +object#pipeline-wide { display: block; } +object#pipeline-narrow { display: none; } + @media screen and (max-width: 1140px) { div#sidebar { display: none; @@ -1150,6 +1161,7 @@ a.textlink { color: #333; } -ul#binding_sidebar { - background: #eee; +@media screen and (max-width: 980px) { + object#pipeline-wide { display: none; } + object#pipeline-narrow { display: block; width: 100%; max-width: 400px; margin: auto; } } diff --git a/doc/developer/ci.md b/doc/developer/ci.md new file mode 100644 index 0000000000..d00dfb5a14 --- /dev/null +++ b/doc/developer/ci.md @@ -0,0 +1,156 @@ +# mlpack continuous integration (CI) systems + +Every pull request submitted to mlpack goes through a number of automated checks +to make sure that all unit tests pass, all code matches the desired style guide, +documentation does not contain any broken links, and so on and so forth. + +In general, all CI checks need to pass for PRs to be merged, but like any +complex project, there are occasionally spurious failures or other unrelated +problems. + + * [Basic compilation and test jobs](#basic-compilation-and-test-jobs) + * [R build](#r-build) + * [Documentation build and test](#documentation-build-and-test) + * [Style checks](#style-checks) + * [Cross-compilation checks](#cross-compilation-checks) + * [Static code analysis checks](#static-code-analysis-checks) + +Also you can see the [list of CI infrastructure](#list-of-ci-infrastructure). + +## Basic compilation and test jobs + +Basic compilation and testing is done on Azure Pipelines. +We use Azure Pipelines primarily because of the large number of resources that +an mlpack build takes; our own [internal resources](#list-of-ci-infrastructure) +are thus preserved for more specific usage. + +Link: [***mlpack on Azure Pipelines***](https://dev.azure.com/mlpack/mlpack/_build/) + + * Builds and tests mlpack for Linux, OS X, and Windows. + + * Also builds and tests bindings on Linux and OS X. + + * Configurations for these jobs can be found in the mlpack repository under the + `.ci/` directory. + + * *These jobs are most of what's shown in the jobs in a PR.* + +***If your build is failing on Azure Pipelines:*** + + * Take a look at the build log to identify the issue. + + * If the failure is during `mlpack_test`, look through the test output to find + where the actual failed test is. + - If the failed test is related to your code, you probably have a bug to fix. + :) + - If the failed test does not seem related at all, it could be a spurious + error in another test. + - You can run the test locally with `bin/mlpack_test NameOfTest`. + - If the test seems like a random failure, try different random seeds: + `bin/mlpack_test --rng-seed=X NameOfTest`. + +## R build + +The R build uses Github Actions (not for any particular reason). + +Link: [***mlpack R build actions***](https://github.com/mlpack/mlpack/actions/workflows/main.yml) + + * Job configuration is found in `.github/workflows/main.yml` + + * The job produces 1 artifact, which is the tarball that can be uploaded to + [CRAN](https://cran.r-project.org/). + + * When this job fails, it is usually because of: + - An intermittent problem downloading dependencies or setting up the + environment. + - A test failure which can probably be more easily debugged or reproduced via + the main [Azure Pipelines build jobs](#basic-compilation-and-test-jobs). + +## Documentation build and test + +The 'documentation build and test' job builds and tests *all* documentation, +checking: + + * that all Markdown pages build and render properly; + * that all HTML is valid; + * that all links referenced in the documentation are valid; + * that all code examples compile and run. + +All of the scripts to perform these builds are located in the `scripts/` +directory, so that they can be run locally. + + * `./scripts/build-docs.sh` + - Builds all documentation in `doc/` with the output directory `doc/html/`. + - If you browse to `doc/html/index.html` you can browse locally-built + documentation. + - Checks all HTML links and anchors. + + * `./scripts/test-docs.sh doc/` + * `./scripts/test-docs.sh doc/path/to/file.md` + - Extracts code blocks from documentation and compiles and runs them. + - Can be run on either all the documentation (with `doc/` or directory + argument), or a single file. + - May require `CXX`, `CXXFLAGS`, and `LDFLAGS` environment variables to be + set. See the script itself for more details. + - If run on an individual file, the output of each compiled code snippet will + be printed. + +When writing new documentation, be sure to test it locally---going back and +forth with the +[job on Jenkins](http://ci.mlpack.org/job/pull-request%20documentation%20build%20and%20test/) +can be very tedious. + +## Style checks + +The [style checker job](http://ci.mlpack.org/job/pull-requests%20mlpack%20style%20checks/) runs on Jenkins. + + * The [`lint.sh` script](https://github.com/mlpack/jenkins-conf/blob/master/linter/lint.sh) to check for C++ style issues. + + * If your job failed this check, look at the "Style-Check Warnings" tab in the + Jenkins job. + + * See also the + [style guidelines for mlpack](https://github.com/mlpack/mlpack/wiki/DesignGuidelines). + +## Cross-compilation checks + +The [cross-compilation checks](http://ci.mlpack.org/job/CrossCompile-mlpack-for-embedded-aarch64/) +run on Jenkins. + + * The job builds mlpack in a + [cross-compilation environment](../embedded/supported_boards.md). + + * Any failures seen here *that are not seen in other jobs* will probably be + failures specific to the cross-compilation environment. + +## Static code analysis checks + +The [static code analysis checks](http://ci.mlpack.org/job/pull-requests-mlpack-static-code-analysis/) +use a few C++ code analysis tools to try and report issues with the codebase. + +Currently, most of the output by this job is not actionable---there are too many +false positives or spurious issues---and therefore should be used only as +informational output. + +Configuration can be found in the +[`jenkins-conf` repository](https://github.com/mlpack/jenkins-conf). + +## List of CI infrastructure + +Many physical systems are involved with testing mlpack and are hooked up to +Jenkins. + +Link: [***Jenkins (`ci.mlpack.org`)***](http://ci.mlpack.org) + + * The 'specialized' build system. + + * Various Jenkins configuration related resources are found in the + [`jenkins-conf` repository](https://github.com/mlpack/jenkins-conf/). + + * The list of workers (individual systems) can be found + [here](http://ci.mlpack.org/computer/). + + * Adding or modifying jobs requires privileges; you can either ask an mlpack + maintainer to make changes, or if you are on the Contributors team but still + don't have access, ask somewhere and someone will give you access. (Probably + `#mlpack:matrix.org` is the best bet!) diff --git a/doc/developer/community.md b/doc/developer/community.md index 4687667645..0e2ed4a479 100644 --- a/doc/developer/community.md +++ b/doc/developer/community.md @@ -18,7 +18,7 @@ via issues on GitHub, or via chat: ## Real-time chat - * #mlpack:matrix.org on [Matrix](https://www.matrix.org/) + * `#mlpack:matrix.org` on [Matrix](https://www.matrix.org/) * [mlpack Slack workspace](https://mlpack.slack.com/) - You will need to request an invite from the [auto-inviter](http://slack-inviter.mlpack.org:4000). @@ -27,11 +27,10 @@ via issues on GitHub, or via chat: ## Video meetup -On the first and third Friday of every month, at ***1700 UTC*** on Fridays, we -have *casual video meetups* with no particular agenda. Feel free to join up! -We often talk about code changes that we are working on, issues that people are -having with mlpack, general design direction, and whatever else might be on our -mind. +On the first Monday of every month, at ***1530 UTC***, we have *casual video +meetups* with no particular agenda. Feel free to join up! We often talk about +code changes that we are working on, issues that people are having with mlpack, +general design direction, and whatever else might be on our mind. We use [this Zoom room](https://zoom.us/j/3820896170). For security, we use a password for the meeting to keep malicious bots out. The password is simple: @@ -55,9 +54,8 @@ contains many examples you can build and play around with. Once you have an idea of what's included in mlpack and how a user might use it, then a good next step would be to set up a development environment. Once you -have that set up, you can -[build mlpack from source](../README.md#3-installing-and-using-mlpack-in-c), -and explore the codebase to see how it's organized. +have that set up, you can [build mlpack from source](../user/install.md), and +explore the codebase to see how it's organized. Try making small changes to the code, or adding new tests to the test suite, and then rebuild to see how your changes work. diff --git a/doc/developer/developers.md b/doc/developer/developers.md new file mode 100644 index 0000000000..0db187975b --- /dev/null +++ b/doc/developer/developers.md @@ -0,0 +1,29 @@ +# Developers + +If you want to contribute to mlpack, or if you already are a regular contributor +to mlpack or a maintainer, the following pages may serve as useful documentation +about internal development processes, guidelines, and systems: + + * [Community](community.md): details of how the mlpack community operates and + communicates, including *how to get involved*. + + * [Google Summer of Code](gsoc.md): advice on applying to mlpack for Google + Summer of Code. + + * [CI/CD](ci.md): systems and servers involved in mlpack's continuous + integration pipeline. + + * [Timers](timer.md): interface for timing bindings and other mlpack programs. + + * [Automatic binding system](bindings.md): design details and operation of + mlpack's automatic binding generator, including how to add a new language. + + * [Writing a binding](iodoc.md): a tutorial on writing an mlpack binding that + will automatically be compiled to any language mlpack has bindings for. + + * [Template policies](policies.md): documentation for standardized class + interfaces used by mlpack algorithms. + - [The ElemType policy](elemtype.md) + - [The DistanceType policy](distances.md) + - [The KernelType policy](kernels.md) + - [The TreeType policy](trees.md) diff --git a/doc/developer/gsoc.md b/doc/developer/gsoc.md index 92583c1f85..5b606ecbbb 100644 --- a/doc/developer/gsoc.md +++ b/doc/developer/gsoc.md @@ -35,12 +35,11 @@ project. A student should ideally be familiar with - *using the development toolchain on your computer*: you should be able to download and compile mlpack, make changes to the code, and recompile with the - new changes. There is a - [section in the README](../README.md#3-installing-and-using-mlpack-in-c) - for how to build mlpack and would be a great place to get started. If you’re - on Windows, then the [Windows build guide](../user/build_windows.md) could be - very useful. See also the [Community page](community.md) for more information - on getting started. + new changes. There is a [guide](../user/install.md) for how to build mlpack + and that would be a great place to get started. If you’re on Windows, then + the [Windows build guide](../user/build_windows.md) could be very useful. See + also the [Community page](community.md) for more information on getting + started. - *at least intermediate C++ knowledge*: mlpack uses lots of different C++ paradigms including template metaprogramming, C++ features like rvalue diff --git a/doc/developer/policies.md b/doc/developer/policies.md new file mode 100644 index 0000000000..763834a125 --- /dev/null +++ b/doc/developer/policies.md @@ -0,0 +1,9 @@ +# Template policies + +mlpack has a number of common template policy patterns that are used in various +algorithms. + + * [The ElemType policy](elemtype.md) + * [The DistanceType policy](distances.md) + * [The KernelType policy](kernels.md) + * [The TreeType policy](trees.md) diff --git a/doc/embedded/crosscompile_armv7.md b/doc/embedded/crosscompile_armv7.md index c0c78f233e..858f690e1e 100644 --- a/doc/embedded/crosscompile_armv7.md +++ b/doc/embedded/crosscompile_armv7.md @@ -87,7 +87,7 @@ the target. In this tutorial we use the autodownloader since it automates the entire process, including the cross-compilation of OpenBLAS. The first step is to create a build directory, just like the -[regular build process](../../README.md#3-installing-and-using-mlpack-in-c): +[regular build process](../user/install.md#install-from-source): ```sh cd mlpack/ diff --git a/doc/img/github.svg b/doc/img/github.svg new file mode 100644 index 0000000000..a8d1174049 --- /dev/null +++ b/doc/img/github.svg @@ -0,0 +1,3 @@ + + + diff --git a/doc/img/gopher.svg b/doc/img/gopher.svg new file mode 100644 index 0000000000..4a779289da --- /dev/null +++ b/doc/img/gopher.svg @@ -0,0 +1,36 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/doc/img/julia.svg b/doc/img/julia.svg new file mode 100644 index 0000000000..169e7a26a5 --- /dev/null +++ b/doc/img/julia.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/doc/img/pipeline-narrow.svg b/doc/img/pipeline-narrow.svg new file mode 100644 index 0000000000..e9514687fb --- /dev/null +++ b/doc/img/pipeline-narrow.svg @@ -0,0 +1,289 @@ + + + + + + + + Prerequisites + + + + Installing mlpack + + + Cross-compilation setup + + + Quickstart + + + Matrices and data + + + + + + + + Tutorials and Examples + + + + + mlpack examples repository + + + + mlpack Youtube channel + + + + mlpack models repository + + + + + + + + Utility Classes + + Math + Distances + Distributions + Kernels + + Trees + + + + + + The Data Science Pipeline + with mlpack + + + + + + + + + + + Data loading and I/O + + + + Numeric data + + + Mixed categorical data + + + Image data + + + mlpack models and objects + + + + + + + + + + + + Preprocessing / feature extraction + + + + Normalizing labels + + + Dataset splitting + + + + + + + + + + + Transformations + + + + AMF + + + LocalCoordinateCoding + + + LMNN + + + NCA + + + NMF + + + PCA + + + RADICAL + + + SparseCoding + + + + + + + + + + + Modeling + + + + Classification + + + Regression + + + Clustering + + + Geometric algorithms + + + + + + + + + + + Evaluation + + + + + Cross-validation + + + Hyperparameter tuning + + + + + + + + + + + Deployment + + + + Compile an mlpack program + + + + Cross-compile to a Raspberry +Pi + + Deploy mlpack on Windows + + + + + + + + + + + + + Bindings + + + + + Python + + + + Julia + + + + CLI + + + + R + + + + Go + + + + + + + Developer documentation + + + + Community + + + GSoC + + + CI/CD + + + Timing + + + Binding system + + + Writing a binding + + + Template policies + + + + diff --git a/doc/img/pipeline-top-1.svg b/doc/img/pipeline-top-1.svg new file mode 100644 index 0000000000..7f4ad39553 --- /dev/null +++ b/doc/img/pipeline-top-1.svg @@ -0,0 +1,81 @@ + + + + + + + The Data Science Pipeline with mlpack + + + + + + + Data loading + and I/O + + + + + + + + + + Preprocessing / + feature extraction + + + + + + + + + + + Transformations + + + + + + + + + + + Modeling + + + + + + + + + + + Evaluation + + + + + + + + + + + Deployment + + + diff --git a/doc/img/pipeline-top-2.svg b/doc/img/pipeline-top-2.svg new file mode 100644 index 0000000000..abefd4f3f1 --- /dev/null +++ b/doc/img/pipeline-top-2.svg @@ -0,0 +1,81 @@ + + + + + + + The Data Science Pipeline with mlpack + + + + + + + + Data loading + and I/O + + + + + + + + + + Preprocessing / + feature extraction + + + + + + + + + + Transformations + + + + + + + + + + + Modeling + + + + + + + + + + + Evaluation + + + + + + + + + + + Deployment + + + diff --git a/doc/img/pipeline-top-3.svg b/doc/img/pipeline-top-3.svg new file mode 100644 index 0000000000..437cfe4236 --- /dev/null +++ b/doc/img/pipeline-top-3.svg @@ -0,0 +1,81 @@ + + + + + + + The Data Science Pipeline with mlpack + + + + + + + + Data loading + and I/O + + + + + + + + + + + Preprocessing / + feature extraction + + + + + + + + + + Transformations + + + + + + + + + + Modeling + + + + + + + + + + + Evaluation + + + + + + + + + + + Deployment + + + diff --git a/doc/img/pipeline-top-4.svg b/doc/img/pipeline-top-4.svg new file mode 100644 index 0000000000..58021867c9 --- /dev/null +++ b/doc/img/pipeline-top-4.svg @@ -0,0 +1,81 @@ + + + + + + + The Data Science Pipeline with mlpack + + + + + + + + Data loading + and I/O + + + + + + + + + + + Preprocessing / + feature extraction + + + + + + + + + + + Transformations + + + + + + + + + + Modeling + + + + + + + + + + Evaluation + + + + + + + + + + + Deployment + + + diff --git a/doc/img/pipeline-top-5.svg b/doc/img/pipeline-top-5.svg new file mode 100644 index 0000000000..c4b5df1d76 --- /dev/null +++ b/doc/img/pipeline-top-5.svg @@ -0,0 +1,81 @@ + + + + + + + The Data Science Pipeline with mlpack + + + + + + + + Data loading + and I/O + + + + + + + + + + + Preprocessing / + feature extraction + + + + + + + + + + + Transformations + + + + + + + + + + + Modeling + + + + + + + + + + Evaluation + + + + + + + + + + Deployment + + + diff --git a/doc/img/pipeline-top-6.svg b/doc/img/pipeline-top-6.svg new file mode 100644 index 0000000000..fade91c981 --- /dev/null +++ b/doc/img/pipeline-top-6.svg @@ -0,0 +1,81 @@ + + + + + + + The Data Science Pipeline with mlpack + + + + + + + + Data loading + and I/O + + + + + + + + + + + Preprocessing / + feature extraction + + + + + + + + + + + Transformations + + + + + + + + + + + Modeling + + + + + + + + + + + Evaluation + + + + + + + + + + Deployment + + diff --git a/doc/img/pipeline-top.svg b/doc/img/pipeline-top.svg new file mode 100644 index 0000000000..cd192bd1bf --- /dev/null +++ b/doc/img/pipeline-top.svg @@ -0,0 +1,83 @@ + + + + + + + The Data Science Pipeline with mlpack + + + + + + + + Data loading + and I/O + + + + + + + + + + + Preprocessing / + feature extraction + + + + + + + + + + + Transformations + + + + + + + + + + + Modeling + + + + + + + + + + + Evaluation + + + + + + + + + + + Deployment + + + diff --git a/doc/img/pipeline-wide.svg b/doc/img/pipeline-wide.svg new file mode 100644 index 0000000000..9ba0a2276a --- /dev/null +++ b/doc/img/pipeline-wide.svg @@ -0,0 +1,290 @@ + + + + + + + + Prerequisites + + + + Installing mlpack + + + Cross-compilation setup + + + Quickstart + + + Matrices and data + + + + + + + + Tutorials and Examples + + + + + mlpack examples repository + + + + mlpack Youtube channel + + + + mlpack models repository + + + + + + + + Utility Classes + + Math + Distances + Distributions + Kernels + + Trees + + + + + + The Data Science Pipeline with mlpack + + + + + + + + + Data loading and I/O + + + + Numeric data + + + Mixed categorical data + + + Image data + + + mlpack models and objects + + + + + + + + + + + + Preprocessing / feature extraction + + + + Normalizing labels + + + Dataset splitting + + + + + + + + + + + Transformations + + + + AMF + + + LocalCoordinateCoding + + + LMNN + + + NCA + + + NMF + + + PCA + + + RADICAL + + + SparseCoding + + + + + + + + + + + + + Modeling + + + + Classification + + + Regression + + + Clustering + + + Geometric algorithms + + + + + + + + + + + Evaluation + + + + + Cross-validation + + + Hyperparameter tuning + + + + + + + + + + + Deployment + + + + Compile an mlpack program + + + + Cross-compile to a Raspberry +Pi + + + Deploy mlpack on Windows + + + + + + + + + + + + Bindings + + + + + Python + + + + Julia + + + + CLI + + + + R + + + + Go + + + + + + + Developer documentation + + + + Community + + + GSoC + + + CI/CD + + + Timing + + + Binding system + + + Writing a binding + + + Template policies + + + + diff --git a/doc/img/python.svg b/doc/img/python.svg new file mode 100644 index 0000000000..84dd1f9539 --- /dev/null +++ b/doc/img/python.svg @@ -0,0 +1,54 @@ + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/doc/img/r.svg b/doc/img/r.svg new file mode 100644 index 0000000000..1fa3ba6d8f --- /dev/null +++ b/doc/img/r.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/doc/img/terminal.svg b/doc/img/terminal.svg new file mode 100644 index 0000000000..f66a93c849 --- /dev/null +++ b/doc/img/terminal.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/doc/img/youtube.svg b/doc/img/youtube.svg new file mode 100644 index 0000000000..b3cfeba4bc --- /dev/null +++ b/doc/img/youtube.svg @@ -0,0 +1,8 @@ + + + + + + + + \ No newline at end of file diff --git a/doc/index.md b/doc/index.md index 4e4ea1cca2..12ab0e6cf3 100644 --- a/doc/index.md +++ b/doc/index.md @@ -2,19 +2,19 @@ -## A fast, flexible machine learning library - mlpack is an intuitive, fast, and flexible header-only C++ machine learning library with bindings to other languages. It aims to provide fast, lightweight implementations of both common and cutting-edge machine learning algorithms. mlpack's lightweight C++ implementation makes it ideal for deployment, and it -can also be used for interactive prototyping via C++ notebooks (these can be -seen in action on mlpack's [homepage](https://www.mlpack.org/)). +can also be used for interactive prototyping via C++ notebooks (see +[here](https://mybinder.org/v2/gh/mlpack/examples/HEAD) for a BinderHub instance +on the [examples repository](https://github.com/mlpack/examples/)). In addition to its [powerful C++ interface](quickstart/cpp.md), mlpack also provides [command-line programs](quickstart/cli.md), and bindings to the @@ -23,209 +23,19 @@ provides [command-line programs](quickstart/cli.md), and bindings to the _If you use mlpack, please [cite the software](citation.md)._ -## mlpack basics +--- -Installing mlpack can be done using the -[instructions in the README](README.md#3-installing-and-using-mlpack-in-c); -or the [Windows build guide](user/build_windows.md). -The following basic guides are *highly recommended* before using mlpack. - - * ***First steps***: - - [mlpack C++ quickstart](quickstart/cpp.md): create a couple simple C++ - programs that use mlpack - - [Sample Windows mlpack C++ application](user/sample_ml_app.md): create a - working mlpack Windows program using Visual Studio - - * ***Basics of matrices and data in mlpack***: - - [Matrices and data in mlpack](user/matrices.md) - - [Loading and saving mlpack objects](user/load_save.md) - - * ***Reference for mlpack core classes***: - - [Core mlpack documentation](user/core.md) - * [Core math utilities](user/core/math.md) - * [Distances](user/core/distances.md) - * [Distributions](user/core/distributions.md) - * [Kernels](user/core/kernels.md) - - * ***Using mlpack natively with our extensions in Python, R, CLI, Julia, and Go***: - - [Links to quickstarts and references](#bindings-to-other-languages) - -## mlpack algorithm documentation - -Documentation for each machine learning algorithm that mlpack implements is -detailed in the sections below. - - * [Classification algorithms](#classification-algorithms): classify points as - discrete labels (`0`, `1`, `2`, ...). - * [Regression algorithms](#regression-algorithms): predict continuous values. - * [Clustering algorithms](#clustering-algorithms): group points into clusters. - * [Geometric algorithms](#geometric-algorithms): computations based on distance - metrics (nearest neighbors, kernel density estimation, etc.). - * [Preprocessing utilities](#preprocessing-utilities): prepare data for machine - learning algorithms. - * [Transformations](#transformations): transform data from one space to - another (principal components analysis, etc.). - * [Modeling utilities](#modeling-utilities): cross-validation, hyperparameter - tuning, etc. - -### Classification algorithms - -Classify points as discrete labels (`0`, `1`, `2`, ...). - - * [`AdaBoost`](user/methods/adaboost.md): Adaptive Boosting - * [`DecisionTree`](user/methods/decision_tree.md): ID3-style decision tree - classifier - * [`HoeffdingTree`](user/methods/hoeffding_tree.md): streaming/incremental - decision tree classifier - * [`LinearSVM`](user/methods/linear_svm.md): simple linear support vector - machine classifier - * [`LogisticRegression`](user/methods/logistic_regression.md): L2-regularized - logistic regression (two-class only) - * [`NaiveBayesClassifier`](user/methods/naive_bayes_classifier.md): simple - multi-class naive Bayes classifier - * [`Perceptron`](user/methods/perceptron.md): simple Perceptron classifier - * [`RandomForest`](user/methods/random_forest.md): parallelized random forest - classifier - * [`SoftmaxRegression`](user/methods/softmax_regression.md): L2-regularized - softmax regression (i.e. multi-class logistic regression) - -### Regression algorithms - -Predict continuous values. - - * [`BayesianLinearRegression`](user/methods/bayesian_linear_regression.md): - Bayesian L2-penalized linear regression - * [`DecisionTreeRegressor`](user/methods/decision_tree_regressor.md): ID3-style - decision tree regressor - * [`LARS`](user/methods/lars.md): Least Angle Regression (LARS), L1-regularized - and L2-regularized - * [`LinearRegression`](user/methods/linear_regression.md): L2-regularized - linear regression (ridge regression) - -### Clustering algorithms - -***NOTE:*** this documentation is still under construction and so some -algorithms that mlpack implements are not yet listed here. For now, see -[the mlpack/methods directory](https://github.com/mlpack/mlpack/tree/master/src/mlpack/methods) -for a full list of algorithms. - -Group points into clusters. - - * [`MeanShift`](user/methods/mean_shift.md): clustering with the density-based - mean shift algorithm - -### Geometric algorithms - -***NOTE:*** this documentation is still under construction and so no geometric -algorithms in mlpack are documented yet. For now, see -[the mlpack/methods directory](https://github.com/mlpack/mlpack/tree/master/src/mlpack/methods) -for a full list of algorithms. - -Computations based on distance metrics. - - - -### Preprocessing utilities - -Prepare data for machine learning algorithms. - - * [Normalizing labels](user/core/normalizing_labels.md): map labels to and from - the range `[0, numClasses - 1]`. - * [Dataset splitting](user/core/split.md): split a dataset into a - training set and a test set. - -***NOTE:*** this documentation is still under construction and so not all -preprocessing utilities in mlpack are documented yet. See also -[the mlpack/methods/preprocess directory](https://github.com/mlpack/mlpack/tree/master/src/mlpack/methods) -for a full list of algorithms. - -### Transformations - -***NOTE:*** this documentation is still under construction and so some -algorithms that mlpack implements are not yet listed here. For now, see -[the mlpack/methods directory](https://github.com/mlpack/mlpack/tree/master/src/mlpack/methods) -for a full list of algorithms. - -Transform data from one space to another. - - * [`AMF`](user/methods/amf.md): alternating matrix factorization - * [`LocalCoordinateCoding`](user/methods/local_coordinate_coding.md): local - coordinate coding with dictionary learning - * [`LMNN`](user/methods/lmnn.md): large margin nearest neighbor (distance - metric learning) - * [`NCA`](user/methods/nca.md): neighborhood components analysis (distance - metric learning) - * [`NMF`](user/methods/nmf.md): non-negative matrix factorization - * [`PCA`](user/methods/pca.md): principal components analysis - * [`RADICAL`](user/methods/radical.md): robust, accurate, direct independent - components analysis (ICA) algorithm - * [`SparseCoding`](user/methods/sparse_coding.md): sparse coding with - dictionary learning - -### Modeling utilities - -Tools for assembling a full data science pipeline. - - * [Cross-validation](user/cv.md): k-fold cross-validation tools for any mlpack - algorithm - * [Hyperparameter tuning](user/hpt.md): generic hyperparameter tuner to find - good hyperparameters for any mlpack algorithm - -## Bindings to other languages - -mlpack's bindings to other languages have less complete functionality than -mlpack in C++, but almost all the same algorithms are available. - -| ***Python*** | -- | [quickstart](quickstart/python.md) | -- | [reference](user/bindings/python.md) | -| ***Julia*** | -- | [quickstart](quickstart/julia.md) | -- | [reference](user/bindings/julia.md) | -| ***R*** | -- | [quickstart](quickstart/r.md) | -- | [reference](user/bindings/r.md) -| ***Command-line programs*** | -- | [quickstart](quickstart/cli.md) | -- | [reference](user/bindings/cli.md) | -| ***Go*** | -- | [quickstart](quickstart/go.md) | -- | [reference](user/bindings/go.md) | - -## mlpack on embedded systems - -mlpack is well suited for embedded systems due to the fact that it is written -in C++ and it is header-only with minimal dependencies. In the following, we are -adding a set of tutorials to allow you to experiment mlpack on various types of -these systems. - -* [cross-compile and run k-NN on a Raspberry Pi 2 (armv7)](embedded/crosscompile_armv7.md) - -## Examples and further documentation - - * [mlpack examples repository](https://github.com/mlpack/examples/): numerous - fully-working example applications of mlpack, in C++ and other languages. - * [mlpack models repository](https://github.com/mlpack/models/): complex models - in C++ built with mlpack - -For additional documentation beyond what is covered in all the resources above, -the source code should be consulted. Each method is fully documented. - -## Developer documentation - -The following general documentation can be useful if you are interested in -contributing to mlpack: - - * [The mlpack community](developer/community.md) - * [mlpack and Google Summer of Code](developer/gsoc.md) - -Throughout the codebase, mlpack uses some common template parameter policies. -These are documented below. - - * [The `ElemType` policy](developer/elemtype.md): element types for data - * [The `DistanceType` policy](developer/distances.md): distance metrics - * [The `KernelType` policy](developer/kernels.md): kernel functions - * [The `TreeType` policy](developer/trees.md): space trees (ball trees, - KD-trees, etc.) - -In addition, the following documentation may be useful when developing bindings -for other languages: - - * [Timers](developer/timer.md): timing parts of bindings - * [Writing an mlpack binding](developer/iodoc.md): simple examples of mlpack - bindings - * [Automatic bindings](developer/bindings.md): details on mlpack's automatic - binding generator system. + + + (Your browser does not support inline SVG objects. Browse the mlpack + pipeline using the navigation sidebar instead.) + + + (Your browser does not support inline SVG objects. Browse the mlpack + pipeline using the navigation sidebar instead.) + ## Changelog diff --git a/doc/quickstart/cli.md b/doc/quickstart/cli.md index 1896dd6226..a7bad2dece 100644 --- a/doc/quickstart/cli.md +++ b/doc/quickstart/cli.md @@ -32,8 +32,9 @@ docker run -it mlpack/mlpack /bin/bash This Docker image has mlpack's command-line bindings already built and installed. -If you prefer to build mlpack from scratch, see the -[main README](../../README.md). +If you prefer to build the command-line programs from scratch, follow the +instructions in the +[installation guide](../user/install.md#compile-bindings-manually). ## Simple quickstart example diff --git a/doc/quickstart/go.md b/doc/quickstart/go.md index ffb6fbe2c9..a0508e8257 100644 --- a/doc/quickstart/go.md +++ b/doc/quickstart/go.md @@ -24,9 +24,12 @@ make sudo make install ``` +After this, `go run my_code.go` will be able to correctly link against mlpack's +Go bindings and run. + Building the Go bindings from scratch is a little more in-depth, though. For information on that, follow the instructions in the -[main README](../../README.md). +[installation guide](../user/install.md#compile-bindings-manually). ## Simple mlpack quickstart example diff --git a/doc/quickstart/julia.md b/doc/quickstart/julia.md index 1d0e0ce68b..9321d97702 100644 --- a/doc/quickstart/julia.md +++ b/doc/quickstart/julia.md @@ -18,7 +18,7 @@ Pkg.add("mlpack") Building the Julia bindings from scratch is a little more in-depth, though. For information on that, follow the instructions in the -[main README](../../README.md). +[installation guide](../user/install.md#compile-bindings-manually). ## Simple quickstart example diff --git a/doc/quickstart/python.md b/doc/quickstart/python.md index 35d7d6b5e7..a13881fc0d 100644 --- a/doc/quickstart/python.md +++ b/doc/quickstart/python.md @@ -26,8 +26,9 @@ Python bindings pre-installed: docker run -it mlpack/mlpack /bin/bash ``` -Otherwise, you can build the Python bindings from scratch using the -documentation in the [main README](../../README.md). +Building the Python bindings from scratch is a little more in-depth, though. +For information on that, follow the instructions in the +[installation guide](../user/install.md#compile-bindings-manually). ## Simple mlpack quickstart example diff --git a/doc/quickstart/r.md b/doc/quickstart/r.md index cc09fa0824..61c5e54023 100644 --- a/doc/quickstart/r.md +++ b/doc/quickstart/r.md @@ -17,7 +17,7 @@ install.packages('mlpack') Building the R bindings from scratch is a little more in-depth, though. For information on that, follow the instructions in the -[main README](../../README.md). +[installation guide](../user/install.md#compile-bindings-manually). ## Simple mlpack quickstart example diff --git a/doc/sidebar.html b/doc/sidebar.html index c428554532..1ca50a7a51 100644 --- a/doc/sidebar.html +++ b/doc/sidebar.html @@ -20,15 +20,18 @@ when the sidebar is built for each page. @@ -382,7 +514,7 @@ when the sidebar is built for each page.
  • - Binding API + Binding API
      diff --git a/doc/user/bindings.md b/doc/user/bindings.md new file mode 100644 index 0000000000..c2f836658c --- /dev/null +++ b/doc/user/bindings.md @@ -0,0 +1,54 @@ +# Bindings to Other Languages + +In addition to the [main C++ interface](../index.md), mlpack also provides +bindings via a simplified API to a number of other languages. This binding API +is consistent across all languages, allowing for easy transition of mlpack code +between languages, + +***Note:*** the binding API is not as flexible or general as the C++ interface; +to get the most out of mlpack, C++ is likely the better route to go. + +## CLI (Command-line programs) + +
      +a terminal +
      + + - [CLI quickstart](../quickstart/cli.md) + - [CLI API reference](bindings/cli.md) + +## Python + +
      +the Python logo +
      + + - [Python quickstart](../quickstart/python.md) + - [Python API reference](bindings/python.md) + +## Julia + +
      +the Julia logo +
      + + - [Julia quickstart](../quickstart/julia.md) + - [Julia API reference](bindings/julia.md) + +## R + +
      +the R logo +
      + + - [R quickstart](../quickstart/r.md) + - [R API reference](bindings/r.md) + +## Go + +
      +the Go gopher +
      + + - [Go quickstart](../quickstart/go.md) + - [Go API reference](bindings/go.md) diff --git a/doc/user/build_windows.md b/doc/user/build_windows.md index 5d562fc0bb..823711ec38 100644 --- a/doc/user/build_windows.md +++ b/doc/user/build_windows.md @@ -155,8 +155,8 @@ manually download ensmallen from http://ensmallen.org/ and extract it to `C:\mlpack\mlpack\build\Debug` (or `C:\mlpack\mlpack\build\Release` if you changed to Release mode) -You are ready to create your first application; take a look at the -[Sample C++ ML App](sample_ml_app.md). +You are ready to create your first application; take a look at +[Deploying mlpack on Windows](deploy_windows.md). ## Building mlpack with Visual Studio's CMake integration diff --git a/doc/user/compile.md b/doc/user/compile.md new file mode 100644 index 0000000000..4d468be8f2 --- /dev/null +++ b/doc/user/compile.md @@ -0,0 +1,154 @@ +# Compile an mlpack program + +Once an mlpack application has been developed, it is easy to compile it into a +standalone program. On this page, compilation is performed via the command-line +on a standard Linux or OS X system; if this is not your environment, see also: + + * [Cross-compile to a Raspberry Pi 2](../embedded/crosscompile_armv7.md) + * [Deploy mlpack on Windows](deploy_windows.md) + +## Simple command-line compilation + +Assuming that mlpack and its dependencies are [installed on the +system](install.md), an mlpack program can be compiled just like any other C++ +program: + +```sh +g++ -std=c++17 -O3 -o mlpack_program mlpack_program.cpp -larmadillo -fopenmp +``` + +The command above uses [gcc](https://gcc.gnu.org/) to compile the program +`mlpack_program.cpp` in C++17 mode with optimizations, using OpenMP for +parallelization. It is expected that `mlpack_program.cpp` has the `int main()` +function defined. + +For more complex applications that have multiple source files, it can often be +easier to develop a simple [`Makefile`](https://www.gnu.org/software/make/manual/html_node/Simple-Makefile.html). + +The [examples repository](https://github.com/mlpack/examples) contains several +standalone C++ projects, each of which have `Makefile`s. These can be adapted +for any project, and are especially useful if any extra include directories or +library directories need to be specified. (This might be the case if, for +instance, mlpack or any dependencies are not installed to standard locations.) + + * [Example adaptable `Makefile`](https://github.com/mlpack/examples/blob/master/cpp/neural_networks/mnist_cnn/Makefile) + +A full list of compiler options to configure the build is beyond the scope of +this simple documentation, but +[this simple list](https://gist.github.com/g-berthiaume/74f0485fbba5cc3249eee458c1d0d386) +has a handful of commonly-used gcc/clang options. + +### Configuring mlpack with compile-time definitions + +Several compilation options can control the behavior of an mlpack program. +These can be specified directly on the command line, or at the top of the +program (before including mlpack or Armadillo!). + +| ***Command-line option*** | ***Code option*** | ***Meaning*** | +|---------------------------|-------------------|---------------| +|*Speed and debugging.* ||| +| `-DNDEBUG` | `#define NDEBUG` | Remove all debugging checks. This can result in slightly faster code, but with no error checking! | +| `-DARMA_NO_DEBUG` | `#define ARMA_NO_DEBUG` | Remove all Armadillo error checking. *Warning:* if there are errors in your code, you are more likely to get a segfault instead of an exception! | +|---------------------------|-------------------|---------------| +|*Output.* ||| +| `-DMLPACK_COUT_STREAM=std::cout` | `#define MLPACK_COUT_STREAM std::cout` | Set the default output stream. (Defaults to `std::cout`.) | +| `-DMLPACK_CERR_STREAM=std::cerr` | `#define MLPACK_CERR_STREAM std::cerr` | Set the default error stream. (Defaults to `std::cerr`.) | +| `-DMLPACK_PRINT_INFO` | `#define MLPACK_PRINT_INFO` | Print information messages (`[INFO ]`) during program execution. | +| `-DMLPACK_PRINT_WARN` | `#define MLPACK_PRINT_WARN` | Print warning messages (`[WARN ]`) during program execution. | +| `-DMLPACK_SUPPRESS_FATAL` | `#define MLPACK_PRINT_FATAL` | Do not print `[FATAL]` messages during program execution. | +| `-DENS_PRINT_INFO` | `#define ENS_PRINT_INFO` | Print informational messages from [ensmallen](https://www.ensmallen.org/) optimizers. | +| `-DENS_PRINT_WARN` | `#define ENS_PRINT_WARN` | Print warning messages from [ensmallen](https://ensmallen.org/) optimizers. | +|---------------------------|-------------------|---------------| +|*Functionality.* ||| +| `-DMLPACK_ENABLE_ANN_SERIALIZATION` | `#define MLPACK_ENABLE_ANN_SERIALIZATION` | Allow neural network layers to be serialized. | +| `-DMLPACK_DISABLE_STB` | `#define MLPACK_DISABLE_STB` | Disable [STB](https://github.com/nothings/stb)-related [image functionality](load_save.md#image-data). | + +***Note:*** If your code serializes (saves or loads) mlpack neural networks, the +`MLPACK_ENABLE_ANN_SERIALIZATION` option must be enabled. This option is not +enabled by default because it can cause compilation time to increase +significantly, but it is necessary for any code that serializes neural networks. + +## Linking without the Armadillo wrapper + +Armadillo, by default, requires linking against the runtime library +`libarmadillo.so` (or `libarmadillo.dylib` or `armadillo.dll` on non-Linux +systems). This library is a convenience library that internally contains all of +the symbols necessary from lower-level libraries (e.g. +[OpenBLAS](https://www.openblas.net/), +[SuperLU](https://portal.nersc.gov/project/sparse/superlu/), +[ARPACK](https://www.arpack.org/), +[HDF5](https://www.hdfgroup.org/solutions/hdf5/), and so on). +When the wrapper library is used, linking against Armadillo means simply typing +`-larmadillo` instead of linking against all of Armadillo's dependencies. + +In some situations this is not preferable, and it is therefore possible via the +[`ARMA_DONT_USE_WRAPPER` macro](https://arma.sourceforge.net/docs.html#config_hpp) +to avoid the Armadillo runtime library and link directly against Armadillo's +dependencies. + +When the Armadillo wrapper library is not being used, a compilation command will +need to be adjusted. For instance, the example of the previous section would +need to be changed to: + +``` +g++ -DARMA_DONT_USE_WRAPPER -std=c++17 -O3 -o mlpack_program mlpack_program.cpp -lopenblas -fopenmp +``` + +Some notes on the command above: + + * Here, `ARMA_DONT_USE_WRAPPER` is specified on the command line instead of in + `mlpack_program.cpp` (or otherwise in the Armadillo + [configuration](https://arma.sourceforge.net/docs.html#config_hpp)). + + * OpenBLAS is used for BLAS/LAPACK support. But, other options include ACML, + reference LAPACK/BLAS, Intel MKL, and so forth. + + * In some programs, especially if sparse matrix support or HDF5 support is + used, it may be necessary to link against other libraries (e.g. `-lSuperLU + -lhdf5`, etc.). The precise set of libraries to link against depends on the + code being used and the system configuration, but it should be easy enough to + use any linker errors to figure out what libraries need to be linked against. + +## Using mlpack in another CMake project + +For complex C++ projects, a build system like CMake may be in use. Adding +mlpack as a dependency to a C++ project is straightforward. The following CMake +code will require mlpack and its dependencies to be available: + +```cmake +# Find mlpack and its dependencies. +find_package(Armadillo REQUIRED) +find_package(cereal REQUIRED) +find_package(ensmallen REQUIRED) +find_package(mlpack REQUIRED) + +include_directories("${ARMADILLO_INCLUDE_DIRS}" "${CEREAL_INCLUDE_DIR}" + "${ENSMALLEN_INCLUDE_DIR}" "${MLPACK_INCLUDE_DIR}") + +# Targets should link against ${ARMADILLO_LIBRARIES}. +``` + +If the relevant files are not available on the system to find those four +packages, they can be downloaded from the +[models](https://github.com/mlpack/models) repository: + + * [`models/CMake` directory](https://github.com/mlpack/models/tree/master/CMake) + +The following files in that directory are necessary (and can be added to the +CMake files for the project): + + * [`ARMA_FindACML.cmake`](https://github.com/mlpack/models/blob/master/CMake/ARMA_FindACML.cmake) + * [`ARMA_FindACMLMP.cmake`](https://github.com/mlpack/models/blob/master/CMake/ARMA_FindACMLMP.cmake) + * [`ARMA_FindARPACK.cmake`](https://github.com/mlpack/models/blob/master/CMake/ARMA_FindARPACK.cmake) + * [`ARMA_FindBLAS.cmake`](https://github.com/mlpack/models/blob/master/CMake/ARMA_FindBLAS.cmake) + * [`ARMA_FindCBLAS.cmake`](https://github.com/mlpack/models/blob/master/CMake/ARMA_FindCBLAS.cmake) + * [`ARMA_FindCLAPACK.cmake`](https://github.com/mlpack/models/blob/master/CMake/ARMA_FindCLAPACK.cmake) + * [`ARMA_FindLAPACK.cmake`](https://github.com/mlpack/models/blob/master/CMake/ARMA_FindLAPACK.cmake) + * [`ARMA_FindMKL.cmake`](https://github.com/mlpack/models/blob/master/CMake/ARMA_FindMKL.cmake) + * [`ARMA_FindOpenBLAS.cmake`](https://github.com/mlpack/models/blob/master/CMake/ARMA_FindOpenBLAS.cmake) + * [`FindArmadillo.cmake`](https://github.com/mlpack/models/blob/master/CMake/FindArmadillo.cmake) + * [`FindEnsmallen.cmake`](https://github.com/mlpack/models/blob/master/CMake/FindEnsmallen.cmake) + * [`Findcereal.cmake`](https://github.com/mlpack/models/blob/master/CMake/Findcereal.cmake) + * [`Findmlpack.cmake`](https://github.com/mlpack/models/blob/master/CMake/Findmlpack.cmake) + + diff --git a/doc/user/core.md b/doc/user/core.md index 55a4c70822..58f194aa7b 100644 --- a/doc/user/core.md +++ b/doc/user/core.md @@ -1,8 +1,8 @@ -# mlpack core class documentation +# Utility classes Underlying the implementations of [mlpack's machine learning -algorithms](../index.md#mlpack-algorithm-documentation) are mlpack core support -classes, each of which are documented in the pages below: +algorithms](../index.md) are mlpack core support classes, each of which are +documented in the pages below: * [Core math utilities](core/math.md): utility classes for mathematical purposes diff --git a/doc/user/core/distances.md b/doc/user/core/distances.md index e1d860157c..eee319bba4 100644 --- a/doc/user/core/distances.md +++ b/doc/user/core/distances.md @@ -31,7 +31,7 @@ including: ## `LMetric` The `LMetric` template class implements a [generalized -L-metric](https://en.wikipedia.org/wiki/Lp_space#Definition) +L-metric](https://en.wikipedia.org/wiki/Lp_space#Preliminaries) (L1-metric, L2-metric, etc.). The class has two template parameters: ``` diff --git a/doc/user/core/trees/binary_space_tree.md b/doc/user/core/trees/binary_space_tree.md index 0ffa6d065b..e4f119682f 100644 --- a/doc/user/core/trees/binary_space_tree.md +++ b/doc/user/core/trees/binary_space_tree.md @@ -1873,13 +1873,13 @@ class BoundType ``` Behavior of some aspects of the `BinarySpaceTree` depend on the traits of a -particular bound. Optionally, you may define a `BoundTraits` specialization for -your bound type, of the following form: +particular bound. Optionally, you may define an `mlpack::BoundTraits` +specialization for your bound type, of the following form: ```c++ // Replace `BoundType` below with the name of the custom class. template -struct BoundTraits> +struct mlpack::BoundTraits> { //! If true, then the bounds for each dimension are tight. If false, then the //! bounds for each dimension may be looser than the range of all points held diff --git a/doc/user/sample_ml_app.md b/doc/user/deploy_windows.md similarity index 95% rename from doc/user/sample_ml_app.md rename to doc/user/deploy_windows.md index 0fede7ab34..de9e08d5ed 100644 --- a/doc/user/sample_ml_app.md +++ b/doc/user/deploy_windows.md @@ -1,12 +1,12 @@ -# Sample C++ ML App for Windows +# Deploying mlpack on Windows *by German Lancioni* This tutorial will help you create a sample machine learning app using -mlpack/C++. Although this app does not cover all the mlpack capabilities, it -will walkthrough several APIs to understand how everything connects. This -Windows sample app is created using Visual Studio, but you can easily adapt it -to a different platform by following the provided source code. +mlpack/C++ on Windows. The tutorial will walk through several APIs to +understand how everything connects. This Windows sample app is created using +Visual Studio, but you can easily adapt it to a different platform by following +the provided source code. *Note*: before starting, make sure you have built mlpack for Windows following this [Windows guide](build_windows.md). diff --git a/doc/user/deployment.md b/doc/user/deployment.md new file mode 100644 index 0000000000..1a0161265a --- /dev/null +++ b/doc/user/deployment.md @@ -0,0 +1,25 @@ + + + +# Deployment + +Once a modeling pipeline is ready for deployment, it is easy to deploy mlpack +applications to a wide variety of settings due to its simple header-only nature. + +See also the [examples repository](https://github.com/mlpack/examples/), +which contains a number of fully-working deployable example applications. + +The pages below provide guidance for how to deploy mlpack to a variety of +relatively simple environments. + + * [***Compile an mlpack program***](compile.md): compile a standalone C++ program + that uses mlpack. + + * [***Cross-compile to a Raspberry Pi***](../embedded/crosscompile_armv7.md): + cross-compile an mlpack C++ application to an embedded or low-resource + device. + - See also the + [cross-compilation setup page](../embedded/supported_boards.md). + + * [***Deploying mlpack on Windows***](deploy_windows.md): build a Windows + application that uses mlpack. diff --git a/doc/user/evaluation.md b/doc/user/evaluation.md new file mode 100644 index 0000000000..f97dc682e1 --- /dev/null +++ b/doc/user/evaluation.md @@ -0,0 +1,12 @@ + + + +# Evaluation + +Once a model is trained, mlpack contains a number of utilities for testing the +model. + + * [Cross-validation](cv.md): k-fold cross-validation tools for any mlpack + algorithm + * [Hyperparameter tuning](hpt.md): generic hyperparameter tuner to find + good hyperparameters for any mlpack algorithm diff --git a/doc/user/install.md b/doc/user/install.md new file mode 100644 index 0000000000..09346c048f --- /dev/null +++ b/doc/user/install.md @@ -0,0 +1,279 @@ +# Installing mlpack + +mlpack is available via a wide variety of sources, depending on what you want to +do with the library. + +***If you want to use mlpack in a C++ program:*** + + * Install via [your system's package manager](#install-via-package-manager) + *(easiest)*. + + * [Install from source](#install-from-source) (see also the + [dependencies](#dependencies) of mlpack). + + * If you are on Windows, see the + [Building mlpack from source on Windows page](build_windows.md). + + * If you intend to cross-compile, see the + [cross-compilation setup page](../embedded/supported_boards.md). + +***If you want to use mlpack's bindings to another language:*** + + * Install mlpack's bindings to other languages via + [language package managers](#install-bindings-via-language-package-managers) + *(easiest)*. + + * [Compile and install bindings manually](#compile-bindings-manually). + +***If you want to develop mlpack:*** + + * [Configure and compile all of mlpack from source](#compile-from-source). + + * Look at the [CMake configuration options](#cmake-options). + + * [Build the tests](#build-tests). + +Once mlpack is installed, try +[compiling a test program](#compiling-a-test-program). + +--- + +## Install via package manager + +The easiest way to install the mlpack C++ library is to use your system package +manager. This will handle mlpack's dependencies automatically. + + * ***Ubuntu/Debian***: `sudo apt-get install libmlpack-dev` + * ***Fedora/RHEL***: `sudo dnf install mlpack-devel` + * ***Arch Linux***: `sudo pacman -S mlpack` + * ***OS X (Homebrew)***: `brew install mlpack` + * ***OS X (MacPorts)***: `sudo port install mlpack` + * ***vcpkg (Windows)***: `vcpkg install mlpack:x64-windows` + * ***conda***: `conda install conda-forge::mlpack` + * ***Conan***: [see here](https://conan.io/center/recipes/mlpack) + +You can also use the +[`mlpack/mlpack` image on DockerHub](https://hub.docker.com/r/mlpack/mlpack) for +a container with mlpack already installed. + +If you plan to write mlpack programs, make sure you have a C++ compiler that +supports C++17 available (this may not be automatically installed by the package +manager). + +## Install from source + +If you only intend to use mlpack in a C++ program, it is not necessary to +[configure and compile from source](#compile-from-source), because mlpack is a +header-only library. This means that you can simply +[download mlpack](https://www.mlpack.org/download.html) and unpack it, and when +you are [compiling a program](#compiling-a-test-program), you must make sure +that the `src/` directory is on the include path. + +With most compilers, this means you simply add the flag `-I/path/to/mlpack/src/` +to the compiler command-line (e.g., +`g++ -I/path/to/mlpack/src/ -o program program.cpp -larmadillo`). + +--- + +If you wish to install the mlpack headers to your system manually via CMake, you +can use the following commands: + +```sh +mkdir build && cd build/ +cmake .. +sudo make install +``` + +Alternately, since CMake v3.14.0, the `cmake` command can create the build +folder itself, and so the above commands can be rewritten as follows: + +```sh +cmake -S . -B build +sudo cmake --build build --target install +``` + +### Dependencies + +You must also ensure that the dependencies of mlpack are available to the +compiler: + + - [Armadillo](https://arma.sourceforge.net)   >= 10.8 + - [ensmallen](https://ensmallen.org)  >= 2.10.0 + - [cereal](http://uscilab.github.io/cereal/)     >= 1.1.2 + +Dependencies can be installed using the system package manager. For example, +on Debian and Ubuntu, all relevant dependencies can be installed with `sudo +apt-get install libarmadillo-dev libensmallen-dev libcereal-dev libstb-dev g++ +cmake`. + +If the STB library headers are available, image loading support will be +available. + +If you are compiling Armadillo by hand, ensure that LAPACK and BLAS are enabled. + +If you are configuring mlpack with CMake (as in the code snippets in the +previous section), you can use the auto-downloader to obtain mlpack's +dependencies with the `-DDOWNLOAD_DEPENDENCIES=ON` option (detailed in the +[CMake options section](#cmake-options). The autodownloader is especially +useful for [cross-compilation](../embedded/supported_boards.md), as it +automatically downloads and compiles OpenBLAS for the target architecture. + +## Install bindings via language package managers + +If you wish to use mlpack's bindings to other languages, see the quickstarts for +each language for more information on installation: + + * [Python](../quickstart/python.md) + * [Command-line](../quickstart/cli.md) + * [Julia](../quickstart/julia.md) + * [R](../quickstart/r.md) + * [Go](../quickstart/go.md) + +## Compile bindings manually + +It is possible to manually build the bindings from source. However, this is not +recommended, as building bindings for a specific language often requires some +amount of setup and is not often a user-friendly process. Specifically, after +the bindings are built, deploying them to the environment of the target language +can be non-trivial and requires knowledge specific to that language (not covered +here). + +To compile bindings for a particular language, follow the +[Compile from source](#compile-from-source) section below, and enable the +appropriate [CMake options](#cmake-options). + +The results of bindings will be built into `build/src/mlpack/bindings//` +where `build/` is the build directory configured with CMake, and `` should +be replaced with the appropriate language (`python`/`r`/`go`/`julia`). There +are two exceptions: + + * Command-line bindings will be built into `build/bin/`. + * Markdown bindings will produce Markdown files in `build/doc/`. + +## Compile from source + +If you intend to develop mlpack, or want to build the tests or bindings to +another language (including the command-line bindings), you will need to compile +from source. Once you have installed [the dependencies](#dependencies) and +[downloaded mlpack](https://www.mlpack.org/download.html), unpack the sources +and configure with CMake. + +The command below enables building the tests and the command-line programs. +More options are detailed in the [CMake options section](#cmake-options). + +```sh +mkdir build && cd build/ +cmake -DBUILD_TESTS=ON -DBUILD_CLI_EXECUTABLES=ON ../ +make -j4 +``` + +The `-j4` option specifies that 4 cores should be used for the build; if you are +running into RAM limitations (or don't have four cores), reduce this. If you +have more cores available, you can increase the number of cores for a faster +build. + +### CMake options + +The following options can be used when configuring mlpack. + +| ***Option*** | ***Description*** | ***Default*** | +|--------------|-------------------|---------------| +| ***General configuration*** ||| +| `-DDOWNLOAD_DEPENDENCIES=ON` | Download all dependencies that are not found on the system. | `OFF` | +| `-DDEBUG=ON` | Compile with debugging symbols. | `OFF` | +| `-DPROFILE=ON` | Compile with profiling symbols. | `OFF` | +| `-DARMA_EXTRA_DEBUG=ON` | Emit extra Armadillo debugging output (warning: *very* verbose). | `OFF` | +| `-DTEST_VERBOSE=ON` | Emit verbose output when running tests. | `OFF` | +| `-DBUILD_TESTS=ON` | Build `mlpack_test`. | `OFF` | +| `-DUSE_OPENMP=ON` | Use OpenMP for parallelization. | `ON` | +| `-DUSE_PRECOMPILED_HEADERS=OFF` | Disable precompiled headers during build. | +`OFF` | +|--------------|-------------------|---------------| +| ***Dependency locations*** ||| +| `-DARMADILLO_INCLUDE_DIR=/path/to/arma/include/` | Path containing `armadillo` header file. || +| `-DARMADILLO_LIBRARY=/path/to/libarmadillo.so` | Path of compiled Armadillo library (if using the Armadillo wrapper library). || +| `-DARMADILLO_LIBRARIES=/path/to/lib1.so;/path/to/lib2.so` | List of libraries to link against for Armadillo (if not using the Armadillo wrapper library). || +| `-DCEREAL_INCLUDE_DIR=/path/to/cereal/include/` | Path containing cereal headers. || +| `-DENSMALLEN_INCLUDE_DIR=/path/to/ens/include/` | Path containing `ensmallen.hpp`. || +| `-DSTB_INCLUDE_DIR=/path/to/stb/include/` | Path containing `stb.h` and `stb_image.h`. || +|--------------|-------------------|---------------| +| ***Bindings*** ||| +| `-DBUILD_CLI_EXECUTABLES=ON` | Enable building command-line programs. | `OFF` | +| `-DBUILD_PYTHON_BINDINGS=ON` | Enable building Python bindings. | `OFF` | +| `-DPYTHON_EXECUTABLE=/path/to/python` | Location of Python program to use. || +| `-DBUILD_GO_BINDINGS=ON` | Enable building Go bindings. | `OFF` | +| `-DBUILD_GO_SHLIB=OFF` | Do not shared library for Go bindings. | `ON` | +| `-DBUILD_JULIA_BINDINGS=ON` | Enable building Julia bindings. | `OFF` | +| `-DJULIA_EXECUTABLE=/path/to/julia` | Location of Julia interpreter. || +| `-DBUILD_R_BINDINGS=ON` | Enable building R bindings. | `OFF` | +| `-DBUILD_MARKDOWN_BINDINGS=ON` | Enable building Markdown bindings (e.g. Markdown documentation for each binding language). | `OFF` | +|--------------|-------------------|---------------| + +### Build tests + +If you are developing mlpack or simply want to run the test suite, after you +have configured the library with CMake, you can build the tests directly: + +```sh +make -j4 mlpack_test +``` + +Replace the `-j4` with the number of cores desired for building. + +Once the build is complete (it may take a while!), you can run the tests from +the build directory, selecting either all of them or an individual test suite. + +```sh +bin/mlpack_test +bin/mlpack_test [LARSTest] +``` + +The `mlpack_test` program uses the [Catch2](https://github.com/catchorg/Catch2) +library for unit testing; this supports many options---you can see them with +`mlpack_test -h`. + +## Compiling a test program + +Once mlpack is installed and available on the system, it is easy to compile a +program using mlpack. For instance, consider the trivial program below: + +```c++ +#include + +using namespace mlpack; + +int main() +{ + // Sample a point from a 3-dimensional Gaussian distribution. + GaussianDistribution g(3); + std::cout << "Random sample from 3D Gaussian: " << std::endl + << g.Random(); +} +``` + +This can be compiled with the command: + +``` +g++ -O3 -std=c++17 -o my_program my_program.cpp -larmadillo -fopenmp +``` + +The command may need slight adaptation if you are using a different compiler or +prefer different compilation options. + +***Notes***: + + - If you want to serialize (save or load) neural networks, you should add + `#define MLPACK_ENABLE_ANN_SERIALIZATION` before including ``. + + - When the autodownloader is used to download Armadillo + (`-DDOWNLOAD_DEPENDENCIES=ON`), the Armadillo runtime library is not built + and Armadillo must be used in header-only mode. Instead, you must link + directly with the dependencies of Armadillo. For example, on a system that + has OpenBLAS available, compilation can be done like this: + +```sh +g++ -O3 -std=c++17 -o my_program my_program.cpp -lopenblas -fopenmp +``` + +See [the Armadillo documentation](https://arma.sourceforge.net/faq.html#linking) +for more information on linking Armadillo programs. diff --git a/doc/user/load_save.md b/doc/user/load_save.md index a5c7e874ea..4a7e76cc5d 100644 --- a/doc/user/load_save.md +++ b/doc/user/load_save.md @@ -1,4 +1,7 @@ -# Loading and saving in mlpack + + + +# Data loading and I/O mlpack provides the `data::Load()` and `data::Save()` functions to load and save [Armadillo matrices](matrices.md) (e.g. numeric and categorical datasets) and diff --git a/doc/user/methods/adaboost.md b/doc/user/methods/adaboost.md index b7fb991b3f..0696e839e0 100644 --- a/doc/user/methods/adaboost.md +++ b/doc/user/methods/adaboost.md @@ -49,7 +49,7 @@ std::cout << arma::accu(predictions == 3) << " test points classified as class " #### See also: - * [mlpack classifiers](../../index.md#classification-algorithms) + * [mlpack classifiers](../modeling.md#classification) * [`Perceptron`](perceptron.md) * [`DecisionTree`](decision_tree.md) * [AdaBoost on Wikipedia](https://en.wikipedia.org/wiki/AdaBoost) diff --git a/doc/user/methods/amf.md b/doc/user/methods/amf.md index d593e875fd..8c90bb1f91 100644 --- a/doc/user/methods/amf.md +++ b/doc/user/methods/amf.md @@ -68,7 +68,7 @@ std::cout << "RMSE of reconstructed matrix: " * [`NMF`](nmf.md): non-negative matrix factorization (a version of `AMF`) * [`SparseCoding`](sparse_coding.md) - * [mlpack transformations](../../index.md#transformations) + * [mlpack transformations](../transformations.md) * [Matrix factorization on Wikipedia](https://en.wikipedia.org/wiki/Matrix_factorization_(recommender_systems)) ### Template parameter overview diff --git a/doc/user/methods/bayesian_linear_regression.md b/doc/user/methods/bayesian_linear_regression.md index 1757edf0bf..66d6b39f45 100644 --- a/doc/user/methods/bayesian_linear_regression.md +++ b/doc/user/methods/bayesian_linear_regression.md @@ -43,7 +43,7 @@ std::cout << arma::accu(predictions < 0) << " test points predicted to have " #### See also: - * [mlpack regression techniques](../../index.md#regression-algorithms) + * [mlpack regression techniques](../modeling.md#regression) * [`LinearRegression`](linear_regression.md) * [`LARS`](lars.md) * [Bayesian linear regression on Wikipedia](https://en.wikipedia.org/wiki/Bayesian_linear_regression) diff --git a/doc/user/methods/decision_tree.md b/doc/user/methods/decision_tree.md index 5b028a67a3..e591ce2167 100644 --- a/doc/user/methods/decision_tree.md +++ b/doc/user/methods/decision_tree.md @@ -48,7 +48,7 @@ std::cout << arma::accu(predictions == 2) << " test points classified as class " * [`DecisionTreeRegressor`](decision_tree_regressor.md) * [Random forests](random_forest.md) - * [mlpack classifiers](../../index.md#classification-algorithms) + * [mlpack classifiers](../modeling.md#classification) * [Decision tree on Wikipedia](https://en.wikipedia.org/wiki/Decision_tree) * [Decision tree learning on Wikipedia](https://en.wikipedia.org/wiki/Decision_tree_learning) diff --git a/doc/user/methods/decision_tree_regressor.md b/doc/user/methods/decision_tree_regressor.md index b465a5f4f6..9891881c21 100644 --- a/doc/user/methods/decision_tree_regressor.md +++ b/doc/user/methods/decision_tree_regressor.md @@ -53,7 +53,7 @@ std::cout << arma::accu(predictions < 0) << " test points predicted to have " * [`DecisionTree`](decision_tree.md) * [Random forests](random_forest.md) - * [mlpack regression techniques](../../index.md#regression-algorithms) + * [mlpack regression techniques](../modeling.md#regression) * [Decision tree on Wikipedia](https://en.wikipedia.org/wiki/Decision_tree) * [Decision tree learning on Wikipedia](https://en.wikipedia.org/wiki/Decision_tree_learning) diff --git a/doc/user/methods/hoeffding_tree.md b/doc/user/methods/hoeffding_tree.md index 4ca6afeb8c..7ec4a8b1fc 100644 --- a/doc/user/methods/hoeffding_tree.md +++ b/doc/user/methods/hoeffding_tree.md @@ -49,7 +49,7 @@ std::cout << arma::accu(predictions == 2) << " test points classified as class " * [`DecisionTree`](decision_tree.md) * [Random forests](random_forest.md) - * [mlpack classifiers](../../index.md#classification-algorithms) + * [mlpack classifiers](../modeling.md#classification) * [Incremental decision tree on Wikipedia](https://en.wikipedia.org/wiki/Incremental_decision_tree) * [Mining High-Speed Data Streams (pdf)](https://dl.acm.org/doi/pdf/10.1145/347090.347107) diff --git a/doc/user/methods/lars.md b/doc/user/methods/lars.md index 30a50b7a43..6b1b819bbf 100644 --- a/doc/user/methods/lars.md +++ b/doc/user/methods/lars.md @@ -47,7 +47,7 @@ std::cout << arma::accu(predictions < 0) << " test points predicted to have " #### See also: * [`LinearRegression`](linear_regression.md) - * [mlpack regression techniques](../../index.md#regression-algorithms) + * [mlpack regression techniques](../modeling.md#regression) * [Least-angle Regression on Wikipedia](https://en.wikipedia.org/wiki/Least-angle_regression) ### Constructors diff --git a/doc/user/methods/linear_regression.md b/doc/user/methods/linear_regression.md index 96792b24ee..9fa71c6724 100644 --- a/doc/user/methods/linear_regression.md +++ b/doc/user/methods/linear_regression.md @@ -43,7 +43,7 @@ std::cout << arma::accu(predictions < 0) << " test points predicted to have " #### See also: - * [mlpack regression techniques](../../index.md#regression-algorithms) + * [mlpack regression techniques](../modeling.md#regression) * [`LARS`](lars.md) * [Linear Regression on Wikipedia](https://en.wikipedia.org/wiki/Linear_regression) diff --git a/doc/user/methods/linear_svm.md b/doc/user/methods/linear_svm.md index 18d3e37f95..051ca86ead 100644 --- a/doc/user/methods/linear_svm.md +++ b/doc/user/methods/linear_svm.md @@ -42,7 +42,7 @@ std::cout << arma::accu(predictions == 1) << " test points classified as class " #### See also: - * [mlpack classifiers](../../index.md#classification-algorithms) + * [mlpack classifiers](../modeling.md#classification) * [`GaussianDistribution`](../core/distributions.md#gaussiandistribution) * [Naive Bayes classifier on Wikipedia](https://en.wikipedia.org/wiki/Naive_Bayes_classifier) diff --git a/doc/user/methods/local_coordinate_coding.md b/doc/user/methods/local_coordinate_coding.md index 5d68945416..4f9d672608 100644 --- a/doc/user/methods/local_coordinate_coding.md +++ b/doc/user/methods/local_coordinate_coding.md @@ -44,7 +44,7 @@ std::cout << "Average density of encoded test data: " * [`SparseCoding`](sparse_coding.md) * [`LARS`](lars.md) (used internally by `LocalCoordinateCoding`) - * [mlpack transformations](../../index.md#transformations) + * [mlpack transformations](../transformations.md) * [Sparse dictionary learning on Wikipedia](https://en.wikipedia.org/wiki/Sparse_dictionary_learning) * [Nonlinear learning using local coordinate coding (pdf)](https://proceedings.neurips.cc/paper_files/paper/2009/file/2afe4567e1bf64d32a5527244d104cea-Paper.pdf) diff --git a/doc/user/methods/logistic_regression.md b/doc/user/methods/logistic_regression.md index 6fec02564b..c54f1fb5ea 100644 --- a/doc/user/methods/logistic_regression.md +++ b/doc/user/methods/logistic_regression.md @@ -47,7 +47,7 @@ std::cout << arma::accu(predictions == 0) << " test points classified as class " #### See also: * [`SoftmaxRegression`](softmax_regression.md) - * [mlpack classifiers](../../index.md#classification-algorithms) + * [mlpack classifiers](../modeling.md#classification) * [Logistic regression on Wikipedia](https://en.wikipedia.org/wiki/Logistic_regression) ### Constructors diff --git a/doc/user/methods/mean_shift.md b/doc/user/methods/mean_shift.md index 4e2f149f75..522ceae32d 100644 --- a/doc/user/methods/mean_shift.md +++ b/doc/user/methods/mean_shift.md @@ -50,7 +50,7 @@ for (size_t c = 0; c < centroids.n_cols; ++c) #### See also: - * [mlpack clustering algorithms](../../index.md#clustering-algorithms) + * [mlpack clustering algorithms](../modeling.md#clustering) * [mlpack kernels](../core/kernels.md) * [Mean shift on Wikipedia](https://en.wikipedia.org/wiki/Mean_shift) * [Mean Shift, Mode Seeking, and Clustering (pdf)](http://users.isr.ist.utl.pt/~alex/Resources/meanshift.pdf) diff --git a/doc/user/methods/naive_bayes_classifier.md b/doc/user/methods/naive_bayes_classifier.md index d692508af8..9d168d36be 100644 --- a/doc/user/methods/naive_bayes_classifier.md +++ b/doc/user/methods/naive_bayes_classifier.md @@ -42,7 +42,7 @@ std::cout << arma::accu(predictions == 2) << " test points classified as class " #### See also: - * [mlpack classifiers](../../index.md#classification-algorithms) + * [mlpack classifiers](../modeling.md#classification) * [`GaussianDistribution`](../core/distributions.md#gaussiandistribution) * [Naive Bayes classifier on Wikipedia](https://en.wikipedia.org/wiki/Naive_Bayes_classifier) diff --git a/doc/user/methods/nmf.md b/doc/user/methods/nmf.md index ce4e280a8e..d6ac74de1d 100644 --- a/doc/user/methods/nmf.md +++ b/doc/user/methods/nmf.md @@ -52,7 +52,7 @@ std::cout << "RMSE of reconstructed matrix: " * [`AMF`](amf.md): alternating matrix factorization * [`SparseCoding`](sparse_coding.md) - * [mlpack transformations](../../index.md#transformations) + * [mlpack transformations](../transformations.md) * [Non-negative matrix factorization on Wikipedia](https://en.wikipedia.org/wiki/Non-negative_matrix_factorization) * [Learning the parts of objects by non-negative matrix factorization](https://citeseerx.ist.psu.edu/document?repid=rep1&type=pdf&doi=29bae9472203546847ec1352a604566d0f602728) (original NMF paper, pdf) @@ -332,7 +332,7 @@ class CustomTerminationPolicy // Note that W and H may have different types than V (i.e. V may be sparse, // and W and H must be dense.) template - bool IsConverged(const MatType& H, const MatType& W); + bool IsConverged(const WHMatType& H, const WHMatType& W); // Return the value that should be returned for the `nmf.Apply()` function // when convergence has been reached. This is called at the end of diff --git a/doc/user/methods/pca.md b/doc/user/methods/pca.md index b0474ccd44..286a31444f 100644 --- a/doc/user/methods/pca.md +++ b/doc/user/methods/pca.md @@ -39,8 +39,8 @@ std::cout << "The transformed data matrix has size " << dataset.n_rows /* 5 */ #### See also: * [`Radical`](radical.md): independent components analysis - * [mlpack preprocessing utilities](../../index.md#preprocessing-utilities) - * [mlpack transformations](../../index.md#transformations) + * [mlpack preprocessing utilities](../preprocessing.md) + * [mlpack transformations](../transformations.md) * [Principal component analysis on Wikipedia](https://en.wikipedia.org/wiki/Principal_component_analysis) ### Constructors @@ -314,7 +314,7 @@ class CustomDecompositionPolicy // etc.). // * `VecType` is the corresponding vector type to `MatType` (e.g., a // `MatType` of `arma::mat` would mean a `VecType` of `arma::vec`, etc.). - template + template static void Apply(const InMatType& data, const MatType& centeredData, MatType& transformedData, diff --git a/doc/user/methods/perceptron.md b/doc/user/methods/perceptron.md index 019ce7d39e..bfbf6dbcd8 100644 --- a/doc/user/methods/perceptron.md +++ b/doc/user/methods/perceptron.md @@ -53,7 +53,7 @@ std::cout << arma::accu(predictions == 1) << " test points classified as class " * [`NaiveBayesClassifier`](naive_bayes_classifier.md), another simple classifier * [`AdaBoost`](adaboost.md) * [`FFN`](/src/mlpack/methods/ann/ffn.hpp) - * [mlpack classifiers](../../index.md#classification-algorithms) + * [mlpack classifiers](../modeling.md#classification) * [Perceptron on Wikipedia](https://en.wikipedia.org/wiki/Perceptron) ### Constructors diff --git a/doc/user/methods/radical.md b/doc/user/methods/radical.md index d416f5c6af..449d713e26 100644 --- a/doc/user/methods/radical.md +++ b/doc/user/methods/radical.md @@ -42,8 +42,8 @@ std::cout << "Independent components matrix size: " << y.n_rows << " x " #### See also: * [`PCA`](pca.md): principal components analysis - * [mlpack preprocessing utilities](../../index.md#preprocessing-utilities) - * [mlpack transformations](../../index.md#transformations) + * [mlpack preprocessing utilities](../preprocessing.md) + * [mlpack transformations](../transformations.md) * [ICA Using Spacings Estimates of Entropy (pdf)](https://www.jmlr.org/papers/volume4/learned-miller03a/learned-miller03a.pdf) * [Independent components analysis on Wikipedia](https://en.wikipedia.org/wiki/Independent_component_analysis) diff --git a/doc/user/methods/random_forest.md b/doc/user/methods/random_forest.md index fc272ed387..63b49ba81a 100644 --- a/doc/user/methods/random_forest.md +++ b/doc/user/methods/random_forest.md @@ -56,7 +56,7 @@ std::cout << arma::accu(predictions == 3) << " test points classified as class " * [`DecisionTree`](decision_tree.md) * [`DecisionTreeRegressor`](decision_tree_regressor.md) - * [mlpack classifiers](../../index.md#classification-algorithms) + * [mlpack classifiers](../modeling.md#classification) * [Random forest on Wikipedia](https://en.wikipedia.org/wiki/Random_forest) * [Decision tree on Wikipedia](https://en.wikipedia.org/wiki/Decision_tree) * [Leo Breiman's Random Forests page](https://www.stat.berkeley.edu/~breiman/RandomForests/cc_home.htm) diff --git a/doc/user/methods/softmax_regression.md b/doc/user/methods/softmax_regression.md index 1826d03a36..5ce0a5b8ba 100644 --- a/doc/user/methods/softmax_regression.md +++ b/doc/user/methods/softmax_regression.md @@ -48,7 +48,7 @@ std::cout << arma::accu(predictions == 2) << " test points classified as class " #### See also: * [`LogisticRegression`](logistic_regression.md) - * [mlpack classifiers](../../index.md#classification-algorithms) + * [mlpack classifiers](../modeling.md#classification) * [UFLDL Softmax Regression Tutorial](http://deeplearning.stanford.edu/tutorial/supervised/SoftmaxRegression/) ### Constructors diff --git a/doc/user/methods/sparse_coding.md b/doc/user/methods/sparse_coding.md index e21ecfa9ec..b8085d8f69 100644 --- a/doc/user/methods/sparse_coding.md +++ b/doc/user/methods/sparse_coding.md @@ -43,7 +43,7 @@ std::cout << "Average density of encoded test data: " * [`LocalCoordinateCoding`](local_coordinate_coding.md) * [`LARS`](lars.md) (used internally by `SparseCoding`) - * [mlpack transformations](../../index.md#transformations) + * [mlpack transformations](../transformations.md) * [Sparse dictionary learning on Wikipedia](https://en.wikipedia.org/wiki/Sparse_dictionary_learning) * [Efficient sparse coding algorithms (pdf)](https://proceedings.neurips.cc/paper/2006/file/2d71b2ae158c7c5912cc0bbde2bb9d95-Paper.pdf) diff --git a/doc/user/modeling.md b/doc/user/modeling.md new file mode 100644 index 0000000000..6b31cc135f --- /dev/null +++ b/doc/user/modeling.md @@ -0,0 +1,67 @@ + + + +# Modeling + +mlpack contains numerous different machine learning algorithms that can be used +for modeling. + +*Note: this section is under construction and not all functionality is +documented yet.* + +## Classification + +Classify points as discrete labels (`0`, `1`, `2`, ...). + + * [`AdaBoost`](methods/adaboost.md): Adaptive Boosting + * [`DecisionTree`](methods/decision_tree.md): ID3-style decision tree + classifier + * [`HoeffdingTree`](methods/hoeffding_tree.md): streaming/incremental decision + tree classifier + * [`LinearSVM`](methods/linear_svm.md): simple linear support vector machine + classifier + * [`LogisticRegression`](methods/logistic_regression.md): L2-regularized + logistic regression (two-class only) + * [`NaiveBayesClassifier`](methods/naive_bayes_classifier.md): simple + multi-class naive Bayes classifier + * [`Perceptron`](methods/perceptron.md): simple Perceptron classifier + * [`RandomForest`](methods/random_forest.md): parallelized random forest + classifier + * [`SoftmaxRegression`](methods/softmax_regression.md): L2-regularized + softmax regression (i.e. multi-class logistic regression) + +## Regression + +Predict continuous values. + + * [`BayesianLinearRegression`](methods/bayesian_linear_regression.md): + Bayesian L2-penalized linear regression + * [`DecisionTreeRegressor`](methods/decision_tree_regressor.md): ID3-style + decision tree regressor + * [`LARS`](methods/lars.md): Least Angle Regression (LARS), L1-regularized and + L2-regularized + * [`LinearRegression`](methods/linear_regression.md): L2-regularized linear + regression (ridge regression) + +## Clustering + +***NOTE:*** this documentation is still under construction and so some +algorithms that mlpack implements are not yet listed here. For now, see +[the mlpack/methods directory](https://github.com/mlpack/mlpack/tree/master/src/mlpack/methods) +for a full list of algorithms. + +Group points into clusters. + + * [`MeanShift`](methods/mean_shift.md): clustering with the density-based mean + shift algorithm + +## Geometric algorithms + +***NOTE:*** this documentation is still under construction and so no geometric +algorithms in mlpack are documented yet. For now, see +[the mlpack/methods directory](https://github.com/mlpack/mlpack/tree/master/src/mlpack/methods) +for a full list of algorithms. + +Computations based on distance metrics. + + diff --git a/doc/user/preprocessing.md b/doc/user/preprocessing.md new file mode 100644 index 0000000000..450cad0deb --- /dev/null +++ b/doc/user/preprocessing.md @@ -0,0 +1,19 @@ + + + +# Preprocessing / feature extraction + +mlpack provides a number of utilities for data preparation and feature +extraction. These utilities are generally used just before actually applying +any machine learning [transformations](transformations.md) or +[modeling](modeling.md). + +*Note: this section is under construction and not all functionality is +documented yet.* + + * [Normalizing labels](core/normalizing_labels.md): convert labels to/from an + arbitrary range to `[0, numClasses - 1]`, which is the range that mlpack + classifiers require. + + * [Dataset splitting](core/split.md): split a dataset into a training and test + set, optionally including labels. diff --git a/doc/user/prerequisites.md b/doc/user/prerequisites.md new file mode 100644 index 0000000000..c7e92cce6a --- /dev/null +++ b/doc/user/prerequisites.md @@ -0,0 +1,19 @@ +# Prerequisites + +Before using mlpack in an application, it must be installed on the system. + + * [Installing mlpack](install.md): a guide to install mlpack. + + * [Cross-compilation setup](../embedded/supported_boards.md): use this guide if + you plan to cross-compile mlpack C++ programs for another device. + +Once mlpack is set up, you should start with the following resources: + + * [Quickstart](../quickstart/cpp.md): guide to get simple mlpack programs running + in C++. + + * [Matrices and data](matrices.md): details about how data is expected to + be represented in mlpack (via the Armadillo library). + +If you wish to use mlpack's bindings to other languages, see the +[Bindings](bindings.md) page. diff --git a/doc/user/transformations.md b/doc/user/transformations.md new file mode 100644 index 0000000000..fa2d152465 --- /dev/null +++ b/doc/user/transformations.md @@ -0,0 +1,43 @@ + + + +# Transformations + +Once data is [loaded](load_save.html) and any necessary +[preprocessing and feature extraction](preprocessing.md) is done, +one of mlpack's transformations can be used to transform data into a +new space. + +*Note: this section is under construction and not all functionality is +documented yet.* + +## Matrix decompositions + +Decompose a matrix into two or more components. + + * [AMF](methods/amf.md): alternating matrix factorization + * [NMF](methods/nmf.md): non-negative matrix factorization + +## Linear transformations + +Linearly map a matrix onto a new basis, optionally performing dimensionality +reduction. + + * [PCA](methods/pca.md): principal components analysis + * [RADICAL](methods/radical.md): an independent components analysis technique + +## Metric learning techniques + +Learn a [distance metric](core/distances.md) based on a data matrix. + + * [LMNN](methods/lmnn.md): large margin nearest neighbor + * [NCA](methods/nca.md): neighborhood components analysis + +## Coding techniques + +Encode data points in a matrix as a combination of points in a dictionary. + + * [LocalCoordinateCoding](methods/local_coordinate_coding.md): local coordinate + coding with dictionary learning + * [SparseCoding](methods/sparse_coding.md): sparse coding with dictionary + learning diff --git a/doc/user/tutorials.md b/doc/user/tutorials.md new file mode 100644 index 0000000000..b98dc4d61a --- /dev/null +++ b/doc/user/tutorials.md @@ -0,0 +1,41 @@ +# Tutorials and Examples + +mlpack has a number of examples, video tutorials, and other resources showing +usage of the library. + + * [mlpack examples repository](https://github.com/mlpack/examples/): contains + simple examples of mlpack usage for various machine learning tasks, in C++ + and other languages. Both notebooks and standalone programs are available. + +--- + + * [mlpack Youtube channel](https://www.youtube.com/@mlpack): tutorial videos + for getting started with mlpack. + - [Installing mlpack for use in C++](https://www.youtube.com/watch?v=wcEFce7IaS8): + a step-by-step tutorial for installing and using mlpack from C++. + * [Ubuntu/Debian](https://www.youtube.com/watch?v=wcEFce7IaS8&t=46s) + * [Fedora/RHEL](https://www.youtube.com/watch?v=wcEFce7IaS8&t=188s) + * [MacOS (via Homebrew)](https://www.youtube.com/watch?v=wcEFce7IaS8&t=303s) + * [Installing from source](https://www.youtube.com/watch?v=wcEFce7IaS8&t=440s) + * [Installing from source with the autodownloader](https://www.youtube.com/watch?v=wcEFce7IaS8&t=712s) + + - [Using mlpack for command-line data science](https://www.youtube.com/watch?v=M0DLrUVSyrE): + a demonstration of mlpack's command-line bindings. + + - [Simple data science workflow in C++ with mlpack](https://www.youtube.com/watch?v=PD9AqGdkPl8): + a tutorial using random forests and softmax regression in C++ to solve a + simple data science problem. + + - [Development workflow tutorial: VSCode](https://www.youtube.com/watch?v=7DOrMQ2HhBY): + set up an mlpack development environment in VSCode. *This is useful if you + are interested in contributing to mlpack.* + + - [Development workflow tutorial: command-line](https://www.youtube.com/watch?v=3PgFzA5duwc): + set up an mlpack development environment from the command-line. *This is + useful if you are interested in contributing to mlpack.* + +--- + + * [mlpack models repository](https://github.com/mlpack/models/): contains + implementations of specific deep learning models that are too large or + complex for inclusion in the main mlpack library. diff --git a/scripts/test-docs.sh b/scripts/test-docs.sh index c9c1fd89d1..97aff1a003 100755 --- a/scripts/test-docs.sh +++ b/scripts/test-docs.sh @@ -77,70 +77,90 @@ extract_code_blocks() # preceding fence close above it. last_line_fence=1; - # Track whether or not the entire last file corresponded to a class - # declaration. - class_decl=0; - while IFS= read -r line; do if [[ $last_line_fence == 1 ]]; then # Skip this line---it will be a fence opening. last_line_fence=0; - - # Create main() function to wrap the code in. - echo "#include " > $output_prefix$output_file_display.cpp; - echo "" >> $output_prefix$output_file_display.cpp; - - # If we have a class declaration from the previous file, insert it. - if [[ $class_decl == 1 ]]; - then - class_decl=0; - last_output_file_id=$(($output_file_id - 1)); - last_output_file_display=$(printf "%02d" $last_output_file_id); - - cat $output_prefix$last_output_file_display.cpp | awk ' - BEGIN { p=0 } - /int main()/ { p=1 } - /^{/ { if(p == 1) { p=2; o=1 } } - /^}/ { p=0; } - // { if (p == 2 && o == 0) { print substr($0, 3) } o=0 }' >> $output_prefix$output_file_display.cpp; - echo "" >> $output_prefix$output_file_display.cpp; - rm -f $output_prefix$last_output_file_display.cpp; - fi - - echo "int main()" >> $output_prefix$output_file_display.cpp; - echo "{" >> $output_prefix$output_file_display.cpp; continue; fi - if [[ $line == '```'* ]]; + if [[ $line == '```' ]]; then last_line_fence=1; - # Close main() function. - echo "}" >> $output_prefix$output_file_display.cpp; - - # Check after the fact: was this file only a class declaration? If so, we - # want to put it instead into the next file. - has_class1=`grep '^ class\|^ struct' $output_prefix$output_file_display.cpp | wc -l`; - has_class2=`grep '^ };' $output_prefix$output_file_display.cpp | wc -l`; - if [[ "$has_class1" != "0" && "$has_class2" != "0" ]]; + if [ -f $output_prefix$output_file_display.body.cpp ]; then - class_decl=1; - fi; + # Determine whether we need a main() function for the code. Also check + # whether the file is simply a class definition, in which case we don't + # need to do anything except prepare it to be inserted into the next + # example. + has_main=`grep 'int main(' $output_prefix$output_file_display.body.cpp | wc -l`; + has_class1=`grep '^ class\|^ struct' $output_prefix$output_file_display.body.cpp | wc -l`; + has_class2=`grep '^ };' $output_prefix$output_file_display.body.cpp | wc -l`; + class_decl=0; + if [ $has_class1 -ne 0 -a $has_class2 -ne 0 ]; + then + class_decl=1; + fi; - # Detect if we need any to add any special headers. We have to do this - # when we finish with the file... - if [[ `grep 'Eigen::' $output_prefix$output_file_display.cpp | wc -l` -gt 0 ]]; - then - sed -i '1s/^/#include \n/' $output_prefix$output_file_display.cpp; - fi + if [ $has_main -eq 0 -a $class_decl -eq 0 ]; + then + # Create main() function to wrap the code in. + echo "#include " > $output_prefix$output_file_display.cpp; + echo "" >> $output_prefix$output_file_display.cpp; - if [[ `grep 'xt::' $output_prefix$output_file_display.cpp | wc -l` -gt 0 ]]; - then - sed -i '1s/^/#include \n/' $output_prefix$output_file_display.cpp; - sed -i '1s/^/#include \n/' $output_prefix$output_file_display.cpp; + # Insert any class definitions. + if [ -f $output_prefix$output_file_display.defn.cpp ]; + then + cat $output_prefix$output_file_display.defn.cpp >> $output_prefix$output_file_display.cpp; + rm -f $output_prefix$output_file_display.defn.cpp; + fi + + echo "int main()" >> $output_prefix$output_file_display.cpp; + echo "{" >> $output_prefix$output_file_display.cpp; + + # Insert the code itself. + cat $output_prefix$output_file_display.body.cpp >> $output_prefix$output_file_display.cpp; + rm -f $output_prefix$output_file_display.body.cpp; + + # Close main() function. + echo "}" >> $output_prefix$output_file_display.cpp; + elif [[ "$class_decl" == "1" ]]; + then + # If the function is only a class declaration, set it aside, along + # with any other declarations, for the next program. + next_id=$(($output_file_id + 1)); + next_display=$(printf "%02d" $next_id); + if [ -f $output_prefix$output_file_display.defn.cpp ]; + then + mv $output_prefix$output_file_display.defn.cpp $output_prefix$next_display.defn.cpp; + cat $output_prefix$output_file_display.body.cpp >> $output_prefix$next_display.defn.cpp; + rm -f $output_prefix$output_file_display.body.cpp; + else + mv $output_prefix$output_file_display.body.cpp $output_prefix$next_display.defn.cpp; + fi + else + # The file should be able to compile on its own. + mv $output_prefix$output_file_display.body.cpp $output_prefix$output_file_display.cpp; + fi + + # Detect if we need any to add any special headers. We have to do this + # when we finish with the file... + if [ -f $output_prefix$output_file_display.cpp ]; + then + if [[ `grep 'Eigen::' $output_prefix$output_file_display.cpp | wc -l` -gt 0 ]]; + then + sed -i '1s/^/#include \n/' $output_prefix$output_file_display.cpp; + fi + + if [[ `grep 'xt::' $output_prefix$output_file_display.cpp | wc -l` -gt 0 ]]; + then + sed -i '1s/^/#include \n/' $output_prefix$output_file_display.cpp; + sed -i '1s/^/#include \n/' $output_prefix$output_file_display.cpp; + fi + fi fi output_file_id=$(($output_file_id + 1)); @@ -150,35 +170,10 @@ extract_code_blocks() fi # Include indentation (two spaces). - echo " $line" >> $output_prefix$output_file_display.cpp; + echo " $line" >> $output_prefix$output_file_display.body.cpp; done < $input_file.tmp; - # The last file is always invalid---we opened it without knowing whether - # anything would be in it. - rm -f $output_prefix$output_file_display.cpp; - - # Check the "true" last file: if it's only class declarations, no need to - # compile it. - output_file_id=$(($output_file_id - 1)); - output_file_display=$(printf "%02d" $output_file_id); - if [ -f $output_prefix$output_file_display.cpp ]; - then - cat $output_prefix$output_file_display.cpp | awk ' - BEGIN { p=0 } - /int main()/ { p=1 } - /^{/ { if(p == 1) { p=2; o=1 } } - /^}/ { p=0 } - // { if (p == 2 && o == 0) { print substr($0, 3) } o=0 }' >> $output_prefix$output_file_display.cpp.tmp; - has_class1=`grep '^class' $output_prefix$output_file_display.cpp.tmp | wc -l`; - has_class2=`grep '^};' $output_prefix$output_file_display.cpp.tmp | wc -l`; - if [[ "$has_class1" != "0" && "$has_class2" != "0" ]]; - then - # The file's main() function is just a class declaration. Nuke it. - rm -f $output_prefix$output_file_display.cpp; - fi - rm -f $output_prefix$output_file_display.cpp.tmp; - fi - + rm -f $output_prefix*.defn.cpp; # Remove any unused definitions. rm -f $input_file.tmp; } @@ -338,16 +333,18 @@ do declare -a files_to_skip=( # These files have small incomplete snippets that can't compile into # standalone programs. - "sample_ml_app.md" + "deploy_windows.md" "hpt.md" "cv.md" "timer.md" "bindings.md" - "elemtype.md" "iodoc.md" + "distances.md" + "elemtype.md" "kernels.md" - "metrics.md" "trees.md" + # Skip the quickstart, since it depends on some specific data. + "cpp.md" # The tutorials are old and are likely to be replaced, so let's not test # them. "amf.md" @@ -369,8 +366,6 @@ do "q_learning.md" "sac.md" "td3.md" - # Skip quickstarts, although we should eventually test them. - "cpp.md" ); skip=0; diff --git a/src/mlpack/methods/ann/layer/linear_impl.hpp b/src/mlpack/methods/ann/layer/linear_impl.hpp index 59cee4bac5..d19c4dab43 100644 --- a/src/mlpack/methods/ann/layer/linear_impl.hpp +++ b/src/mlpack/methods/ann/layer/linear_impl.hpp @@ -36,7 +36,7 @@ LinearType::LinearType( outSize(outSize), regularizer(regularizer) { - weights.set_size(WeightSize(), 1); + // Nothing to do here. } // Copy constructor. @@ -58,7 +58,9 @@ LinearType::LinearType(LinearType&& layer) : outSize(std::move(layer.outSize)), regularizer(std::move(layer.regularizer)) { - // Nothing else to do. + // Reset parameters of other layer. + layer.inSize = 0; + layer.outSize = 0; } template @@ -87,6 +89,10 @@ LinearType::operator=( inSize = std::move(layer.inSize); outSize = std::move(layer.outSize); regularizer = std::move(layer.regularizer); + + // Reset parameters of other layer. + layer.inSize = 0; + layer.outSize = 0; } return *this; diff --git a/src/mlpack/methods/ann/layer/linear_no_bias_impl.hpp b/src/mlpack/methods/ann/layer/linear_no_bias_impl.hpp index 0736b2a056..cfc015147d 100644 --- a/src/mlpack/methods/ann/layer/linear_no_bias_impl.hpp +++ b/src/mlpack/methods/ann/layer/linear_no_bias_impl.hpp @@ -58,7 +58,9 @@ LinearNoBiasType::LinearNoBiasType( outSize(0), regularizer(std::move(layer.regularizer)) { - // Nothing to do here. + // Reset parameters of other layer. + layer.inSize = 0; + layer.outSize = 0; } template @@ -88,6 +90,10 @@ LinearNoBiasType::operator=( inSize = std::move(layer.inSize); outSize = std::move(layer.outSize); regularizer = std::move(layer.regularizer); + + // Reset parameters of other layer. + layer.inSize = 0; + layer.outSize = 0; } return *this;