Add a readme. Readmes are good.
This commit is contained in:
Ryan Curtin
+214
@@ -0,0 +1,214 @@
|
||||
================================================================================
|
||||
|
||||
mlpack: open-source scalable c++ machine learning library
|
||||
|
||||
================================================================================
|
||||
|
||||
0. Contents
|
||||
|
||||
1. Introduction
|
||||
2. Citation details
|
||||
3. Dependencies
|
||||
4. Building mlpack from source
|
||||
5. Running mlpack programs
|
||||
6. Further documentation
|
||||
7. Bug reporting
|
||||
|
||||
================================================================================
|
||||
|
||||
1. Introduction
|
||||
|
||||
mlpack is an intuitive, fast, scalable C++ machine learning library, meant to be
|
||||
a machine learning analog to LAPACK. It aims to implement a wide array of
|
||||
machine learning methods and function as a "swiss army knife" for machine
|
||||
learning researchers.
|
||||
|
||||
The mlpack website can be found at http://mlpack.org and contains numerous
|
||||
tutorials and extensive documentation. This README serves as a guide for what
|
||||
mlpack is, how to install it, how to run it, and where to find more
|
||||
documentation. The website should be consulted for further information:
|
||||
|
||||
http://www.mlpack.org/
|
||||
|
||||
http://www.mlpack.org/tutorial.html <-- tutorials
|
||||
http://www.mlpack.org/trac/ <-- development site (Trac)
|
||||
http://www.mlpack.org/doxygen.php <-- API documentation
|
||||
|
||||
================================================================================
|
||||
|
||||
2. Citation details
|
||||
|
||||
If you use mlpack in your research or software, please cite mlpack using the
|
||||
citation below (given in BiBTeX format):
|
||||
|
||||
@INPROCEEDINGS{mlpack2011,
|
||||
author = {Ryan R. Curtin and James R. Cline and Neil P. Slagle and Matthew
|
||||
L. Amidon and Alexander G. Gray},
|
||||
title = {{MLPACK: A Scalable C++ Machine Learning Library}},
|
||||
booktitle = {{BigLearning: Algorithms, Systems, and Tools for Learning at
|
||||
Scale}},
|
||||
year = 2011
|
||||
}
|
||||
|
||||
Citations are beneficial for the growth and improvement of mlpack.
|
||||
|
||||
================================================================================
|
||||
|
||||
3. Dependencies
|
||||
|
||||
mlpack has the following dependencies:
|
||||
|
||||
Armadillo >= 2.4.4
|
||||
LibXml2 >= 2.6.0
|
||||
Boost (program_options, math_c99, unit_test_framework, random)
|
||||
CMake >= 2.8.5
|
||||
|
||||
All of those should be available in your distribution's package manager. If
|
||||
not, you will have to compile each of them by hand. See the documentation for
|
||||
each of those packages for more information.
|
||||
|
||||
If you are compiling Armadillo by hand, ensure that LAPACK and BLAS are enabled.
|
||||
|
||||
================================================================================
|
||||
|
||||
4. Building mlpack from source
|
||||
(see also http://www.mlpack.org/doxygen.php?doc=build.html )
|
||||
|
||||
mlpack uses CMake as a build system and allows several flexible build
|
||||
configuration options. One can consult any of numerous CMake tutorials for
|
||||
further documentation, but this tutorial should be enough to get mlpack built
|
||||
and installed.
|
||||
|
||||
First, unpack the mlpack source and change into the unpacked directory. Here we
|
||||
use mlpack-x.y.z where x.y.z is the version.
|
||||
|
||||
$ tar -xzf mlpack-x.y.z.tar.gz
|
||||
$ cd mlpack-x.y.z
|
||||
|
||||
Then, make a build directory. The directory can have any name, not just
|
||||
'build', but 'build' is sufficient.
|
||||
|
||||
$ mkdir build
|
||||
$ cd build
|
||||
|
||||
The next step is to run CMake to configure the project. Running CMake is the
|
||||
equivalent to running `./configure` with autotools. If you run CMake with no
|
||||
options, it will configure the project to build with no debugging symbols and no
|
||||
profiling information:
|
||||
|
||||
$ cmake ../
|
||||
|
||||
You can specify options to compile with debugging information and profiling
|
||||
information:
|
||||
|
||||
$ cmake -D DEBUG=ON -D PROFILE=ON ../
|
||||
|
||||
Options are specified with the -D flag. A list of options allowed:
|
||||
|
||||
DEBUG=(ON/OFF): compile with debugging symbols
|
||||
PROFILE=(ON/OFF): compile with profiling symbols
|
||||
ARMA_EXTRA_DEBUG=(ON/OFF): compile with extra Armadillo debugging symbols
|
||||
BOOST_ROOT=(/path/to/boost/): path to root of boost installation
|
||||
ARMADILLO_INCLUDE_DIR=(/path/to/armadillo/include/): path to Armadillo headers
|
||||
ARMADILLO_LIBRARY=(/path/to/armadillo/libarmadillo.so): Armadillo library
|
||||
|
||||
Other tools can also be used to configure CMake, but those are not documented
|
||||
here.
|
||||
|
||||
Once CMake is configured, building the library is as simple as typing 'make'.
|
||||
This will build all library components as well as 'mlpack_test'.
|
||||
|
||||
$ make
|
||||
|
||||
You can specify individual components which you want to build, if you do not
|
||||
want to build everything in the library:
|
||||
|
||||
$ make pca allknn allkfn
|
||||
|
||||
If the build fails and you cannot figure out why, register an account on Trac
|
||||
and submit a ticket and the mlpack developers will quickly help you figure it
|
||||
out:
|
||||
|
||||
http://mlpack.org/trac/
|
||||
|
||||
Alternately, mlpack help can be found in IRC at #mlpack on irc.freenode.net.
|
||||
|
||||
If you wish to install mlpack to /usr/include/mlpack/ and /usr/lib/ and
|
||||
/usr/bin/, once it has built, make sure you have root privileges (or write
|
||||
permissions to those two directories), and simply type
|
||||
|
||||
# make install
|
||||
|
||||
You can now run the executables by name; you can link against mlpack with
|
||||
-lmlpack, and the mlpack headers are found in /usr/include/mlpack/.
|
||||
|
||||
================================================================================
|
||||
|
||||
5. Running mlpack programs
|
||||
|
||||
After building mlpack, the executables will reside in build/bin/. You can call
|
||||
them from there, or you can install the library and (depending on system
|
||||
settings) they should be added to your PATH and you can call them directly. The
|
||||
documentation below assumes the executables are in your PATH.
|
||||
|
||||
We consider the 'allknn' program, which finds the k nearest neighbors in a
|
||||
reference dataset of all the points in a query set. That is, we have a query
|
||||
and a reference dataset. For each point in the query dataset, we wish to know
|
||||
the k points in the reference dataset which are closest to the given query
|
||||
point.
|
||||
|
||||
Alternately, if the query and reference datasets are the same, the problem can
|
||||
be stated more simply: for each point in the dataset, we wish to know the k
|
||||
nearest points to that point.
|
||||
|
||||
Each mlpack program has extensive help documentation which details what the
|
||||
method does, what each of the parameters are, and how to use them:
|
||||
|
||||
$ allknn --help
|
||||
|
||||
Running allknn on one dataset (that is, the query and reference datasets are the
|
||||
same) and finding the 5 nearest neighbors is very simple:
|
||||
|
||||
$ allknn -r dataset.csv -n neighbors_out.csv -d distances_out.csv -k 5 -v
|
||||
|
||||
The -v (--verbose) flag is optional; it gives informational output. It is not
|
||||
unique to allknn but is available in all mlpack programs. Verbose output also
|
||||
gives timing output at the end of the program, which can be very useful.
|
||||
|
||||
================================================================================
|
||||
|
||||
6. Further documentation
|
||||
|
||||
The documentation given here is only a fraction of the available documentation
|
||||
for mlpack. If doxygen is installed, you can type 'make doc' to build the
|
||||
documentation locally. Alternately, up-to-date documentation is available for
|
||||
older versions of mlpack:
|
||||
|
||||
http://www.mlpack.org/tutorial.html <-- tutorials for mlpack
|
||||
http://www.mlpack.org/doxygen.php <-- API documentation for mlpack
|
||||
http://www.mlpack.org/trac/ <-- development site for mlpack (Trac)
|
||||
|
||||
================================================================================
|
||||
|
||||
7. Bug reporting
|
||||
(see also http://www.mlpack.org/help.html )
|
||||
|
||||
If you find a bug in mlpack or have any problems, numerous routes are available
|
||||
for help.
|
||||
|
||||
Trac is used for bug tracking, and can be found at http://www.mlpack.org/trac/.
|
||||
It is easy to register an account and file a bug there, and the mlpack
|
||||
development team will try to quickly resolve your issue.
|
||||
|
||||
In addition, mailing lists are available. The mlpack discussion list is
|
||||
available at
|
||||
|
||||
https://lists.cc.gatech.edu/mailman/listinfo/mlpack
|
||||
|
||||
and the subversion commit list is available at
|
||||
|
||||
https://lists.cc.gatech.edu/mailman/listinfo/mlpack-svn
|
||||
|
||||
Lastly, the IRC channel #mlpack on Freenode can be used to get help.
|
||||
|
||||
================================================================================
|
||||
Reference in New Issue
Block a user