[mlpack-svn] r14483 - mlpack/trunk
fastlab-svn at coffeetalk-1.cc.gatech.edu
fastlab-svn at coffeetalk-1.cc.gatech.edu
Thu Mar 7 13:52:13 EST 2013
Author: rcurtin
Date: 2013-03-07 13:52:13 -0500 (Thu, 07 Mar 2013)
New Revision: 14483
Added:
mlpack/trunk/README.txt
Log:
Add a readme. Readmes are good.
Added: mlpack/trunk/README.txt
===================================================================
--- mlpack/trunk/README.txt (rev 0)
+++ mlpack/trunk/README.txt 2013-03-07 18:52:13 UTC (rev 14483)
@@ -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):
+
+ at 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.
+
+================================================================================
More information about the mlpack-svn
mailing list