Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
APRIL-ANN toolkit (A Pattern Recognizer In Lua with ANNs). This toolkit incorporates ANN algorithms (as dropout, stacked denoising auto-encoders, convolutional NNs), with other pattern recognition methods as HMMs among others. Additionally, in experimental stage, it is possible to perform automatic differentiation, for advanced ML research.
C++ Lua C HTML Cuda Makefile Other

README.md

APRIL-ANN

Build Status Travis CI (master branch)

Build Status Travis CI (devel branch)

User documentation

Follow wiki for user documentation.

Tutorials

Tutorials are available at april-ann-tutorials repository.

Contributions

Contributions are wellcome. Only pull requests to devel branch will be accepted, so avoid to create pull requests to master. A Travis CI instance will check that your request passes all tests. For Lua unit testing use the package basics/utest, and for C++ unit testing the package basics/gtest. At the end of this document there are information about Doxygen documentation which can be useful for C/C++ developing. For Lua developing use the wiki.

It is possible to make a pull request directly to master branch for bug or memory leak solving.

Dependencies and basic setup

Clone the repository and enter to it:

$ git clone https://github.com/pakozm/april-ann.git
$ cd april-ann

The first time you want to run APRIL-ANN, you need to install dependencies in Linux (via apt-get) and in MacOS X (via MacPorts/Homebrew). There is an automatic shellscript which covers majorly Ubuntu (other Debian based distributions can be supported) and MacOS X systems. You just need to run:

$ ./DEPENDENCIES-INSTALLER.sh

Requirements, installed by previous script

Requires the following libraries. Versions are only orientative, it could work with older and newer versions whenver the API was compatible.

  • GNU C++ compiler (g++): v 4.7.2
  • Only in Linux systems: Lua 5.2 headers to tell APRIL-ANN the default system path for Lua modules (lua5.2-deb-multiarch.h header).
  • BLAS implementation: ATLAS (v. 3), Intel MKL (v. 10.3.6), MacOS Accelerate Framework
  • Threads posix (pthread)
  • Readline (libreadline)
  • OpenMP
  • LAPACK library, offered by liblapack_atlas, mkl_lapack, or MacOS Accelerate Framework
  • LAPACKE library when compiling with ATLAS

The following libreries are recommended, but optional, you will need to remove its package from the path profile_build_scripts/package_list.lua:

  • [OPTIONAL] libpng: if you want to open PNG images, package libpng.
  • [OPTIONAL] libtiff: if you want to open TIFF images, package libtiff.
  • [OPTIONAL] libz: support for open of GZIPPED files, package gzio.
  • [OPTIONAL] libzip: support for open ZIP packages, package zip.

For perform computation on GPU, this optional library, which has an specific make target:

  • [OPTIONAL] CUDA and CUBLAS: release 4.2.6.

Compilation

First, it is mandatory to configure the repo PATH and other stuff. This step is needed every time you start a session, and before compilation:

$ . configure.sh

Second, you can compile the APRIL-ANN version which you need. We have developed compiling files for using different libraries. The most simple compilation way is

$ make

and it would detect automatically your platform (Darwin or Linux) and your target SUFIX (mkl, atlas, macports or homebrew). The automatic targets are:

  • release automatic platform and sufix detection target (the same as make without any argument).
  • debug automatic platform and sufix detection target for debug version.
  • test automatic platform and sufix detection target for test-debug version.

There are available more targets, just depending in your particular system installation you can execute them by using $ make TARGET:

  • release-mkl needs of MKL library installed at /opt/MKL as prefix.
  • release-atlas needs of OMP and ATLAS library.
  • release-no-omp needs ATLAS library.
  • release-cuda-mkl needs CUDA and MKL installed at /opt/MKL as prefix.
  • release-macports needs Mac OS X with MacPorts and Accelerate Framework.
  • release-homebrew needs Mac OS X with Homebrew and Accelerate Framework.

Besides this targets, it is possible to compile for debug replacing release string with debug string, and for testing replacing release by test-debug.

The makefile has the following variables which can be forced by the user:

  • PREFIX indicates the prefix for libraries and binaries. In Linux it is /usr, in Darwin it depends on MacPorts (/opt/local) or Homebrew (/usr/local).
  • LUALIB indicates where Lua modules are installed, by default it is $(PREFIX)/lib/lua/5.2
  • BIN indicates where you want to install binary files, by default it is $(PREFIX)/bin

Each of this targets will need a little configuration depending on your library installation. For example, in order to compile with MKL, the file profile_build_scripts/build_mkl_release.lua contains the following sections (among others):

  global_flags = {
    debug="no",
    use_lstrip = "no",
    use_readline="yes",
    optimization = "yes",
    platform = "unix",
    extra_flags={
      -- For Intel MKL :)
      "-DUSE_MKL",
      "-I/opt/MKL/include",
      --------------------
      "-march=native",
      "-msse",
      "-DNDEBUG",
    },
    extra_libs={
      "-lpthread",
      -- For Intel MKL :)
      "-L/opt/MKL/lib",
      "-lmkl_intel_lp64",
      "-Wl,--start-group",
      "-lmkl_intel_thread",
      "-lmkl_core",
      "-Wl,--end-group",
      "-liomp5"
    },
  },

You need to especify the -I option to the compiler, and all the extra_libs stuff related with MKL. Exists one build file for each possible target: build_release.lua, build_debug.lua, build_mkl_release.lua, build_mkl_debug.lua, ... and so on.

The binary will be generated at bin/april-ann, which incorporates the Lua 5.2 interpreter and works without any dependency in Lua. Besides, a shared library will be generated at lib/aprilann.so, so it is possible to use require from Lua to load APRIL-ANN in a standard Lua 5.2 interpreter.

NOTE that loading april-ann as a Lua 5.2 module, you need to have the .so library in the package.cpath or LUA_CPATH. It is possible to install it in your system defaults following next section.

ENJOY!

Installation

The installation is done executing:

$ sudo make install

This procedure copies the binary to system location in /usr (or in /opt/local for Mac OS X via MacPorts). The shared library is copied to Lua default directory, in order to load it by using require function. If you are using a non default installation (a custom one), please copy the .so files manually to your package.cpath or LUA_CPATH.

Use

  • You can execute the standalone binary:
$ april-ann
APRIL-ANN v0.2.1-beta COMMIT 920  Copyright (C) 2012-2013 DSIC-UPV, CEU-UCH
This program comes with ABSOLUTELY NO WARRANTY; for details see LICENSE.txt.
This is free software, and you are welcome to redistribute it
under certain conditions; see LICENSE.txt for details.
Lua 5.2.2  Copyright (C) 1994-2013 Lua.org, PUC-Rio
> print "Hello World!"
Hello World!
  • It is possible to use APRIL-ANN as a Lua module, loading only the packages which you need (i.e. require("aprilann.matrix")), or loading the full library (require("aprilann")). Be careful, the APRIL-ANN modules doesn't follow Lua guidelines and have lateral effects because of the declaration of tables, functions, and other values at the GLOBALs Lua table:
$ lua
Lua 5.2.2  Copyright (C) 1994-2013 Lua.org, PUC-Rio
> require "aprilann.matrix"
> require "aprilann"
APRIL-ANN v0.2.1-beta COMMIT 920  Copyright (C) 2012-2013 DSIC-UPV, CEU-UCH
This program comes with ABSOLUTELY NO WARRANTY; for details see LICENSE.txt.
This is free software, and you are welcome to redistribute it
under certain conditions; see LICENSE.txt for details.
> print "Hello World!"
Hello World!

Citation

If you are interested in use this software, please cite correctly the source. In academic publications you can use this bibitem:

@misc{aprilann,
  Author = {Francisco Zamora-Mart\'inez and Salvador Espa{\~n}a-Boquera and
            Jorge Gorbe-Moya and Joan Pastor-Pellicer and Adri\'an Palacios-Corella},
  Note = {{https://github.com/pakozm/april-ann}},
  Title = {{APRIL-ANN toolkit, A Pattern Recognizer In Lua with Artificial Neural Networks}},
  Year = {2013}}

Publications

List of research papers which uses this tool:

Our ancient ANN implementation in the former APRIL tookit was published here:

Other projects using it

Competition participations and other projects where APRIL-ANN has been used:

Packages

APRIL-ANN is compiled following a package system. In the directory packages you could find a tree of directory entries. Leaves in the tree are directories which contain file "package.lua". The "package.lua" defines requirements, dependencies, libraries, and other stuff needed by the corresponding package.

Each package could contain this directories:

  • c_src: source files (.h, .cc, .c, .cpp, .cu, and others).
  • binding: binding files (.lua.cc), a kind of templatized file which generates the glue code between C/C++ and Lua.
  • lua_src: lua source files which define functions, tables, and pseudo-classes in Lua.
  • doc: doxygen documentation additional files.
  • test: examples and files for testing.

At root directory exists a file named "package_list.lua". It is a Lua table with the name of packages that you want to compile. If you don't want or don't have libpng, or libtiff, or other library, you could erase the package name from this list to avoid its compilation.

Includes these sources

Wiki documentation

Doxygen documentation

The documentation of the devel branch will be mantained as updated as possible in the following links:

However, you can produce the Doxygen documentation of the branch where you are working by using the makefile's document target. Please, note that you need to have installed Doxygen and Graphviz.

$ make document
$ open doxygen_doc/developer/html/index.html

The last command can be substituted by you opening the indicated location in your prefered web browser ;)

LINUX dependencies installation

Execute: $ ./DEPENDENCIES-INSTALLER.sh

If your distribution is not supported (currently only Ubuntu has support), then install g++, libatlas-dev, libreadline-dev, libpng-dev, libtiff-dev, libz-dev, libopenmp-dev, libzip-dev, liblua5.2-dev.

MAC OS X dependencies installation

Via MacPorts:

  • Install MacPorts
  • Execute $ ./DEPENDENCIES-INSTALLER.sh

Or via HomeBrew:

  • Install Homebrew
  • Execute $ ./DEPENDENCIES-INSTALLER.sh
Something went wrong with that request. Please try again.