Developer notes

Understand MatConvNet and contribute to it

There are several parts to MatConvNet. It is important to understand this modular structure so that everybody can maximally benefit from your contributions. In particular, the easiest way to contribute something of general utility to the library is to create a new building block, as explained below:

  1. Building blocks. The most important are the neural network building blocks, i.e. MATLAB functions prefixed by vl_nn such as vl_nnconv. To add a new "layer" or "computational block", add such a function. These are found in the directory matlab/.

  2. CNN wrappers. There are a few wrappers (vl_simplenn and vl_dagnn) that allow implementing networks composed of several blocks. These are located in matlab/wrappers. These wrappers are fairly generic, but there are case in which writing a new wrapper type may be useful.

  3. C++/CUDA library. While many blocks can be written in MATLAB directly, some such as convolution and max-pooling require custom C++ and CUDA code. In this case, create a MEX file in matlab/src and add the required functionality to the C++/CUDA library by adding files to matlab/src/bits.

  4. Examples. Other components of the library are at the moment delivered as examples in the examples/ directory. This include basic SGD code for training networks in examples/cnn_train.m. Note that these functions are not supposed to have very broad generality, although in practice they can be an excellent starting point to write your own learning algorithms.

If you develop the C++/CUDA core of the library, it may be convenient to switch using an IDE/command line and the Makefile for compiling the library.

Creating the website

MatConvNet website uses the MkDocs documentation system, a simple static website generator written in Python. In order to setup the necessary software, follow these steps:

  1. Install MkDocs as explained here.
  2. Install the MathJax MkDocs extension. This is explained in the README file in the extension GitHub repository and consists in renaming and copying a file into your copy of MkDocs.
  3. Make sure that the mkdocs command is executable from the command line, or otherwise modify the file doc/Makefile in MatConvNet to point to the correct executable.

At this point, the website can be built with make doc-site from the command line. The documentation is created in doc/site/site from the doc/site/docs/*.md files.

For developing the website, it is useful to start the MkDocs HTTP server as follows:

cd doc/site
mkdocs serve

At this point visit http://127.0.0.1:8000/ to see a copy of the current website.

Creating the MATLAB function pages

The documentation for the MATLAB function is extracted automatically from the m-files using the doc/matdoc.py Python script. This is called by doc/Makefile as needed.

matdoc.py does three things: it extracts the function documentation from a m-file, it interprets it using a pseudo-Markdown syntax, and then it writes the result in Markdown format for use with MkDocs. These are stored in doc/site/docs/mfiles.