diff --git a/README.txt b/README.txt new file mode 100644 index 0000000000..f22b719860 --- /dev/null +++ b/README.txt @@ -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. + +================================================================================