Merge pull request BVLC#231 from BVLC/next

0.99 release

.gitignore

@@ -55,4 +55,5 @@ data/*
 examples/*
 
 # Don't version the generated documentation
-docs/_site
+docs/_site
+_site

Makefile

@@ -22,7 +22,9 @@ HXX_SRCS := $(shell find include/$(PROJECT) ! -name "*.hpp")
 # CU_SRCS are the cuda source files
 CU_SRCS := $(shell find src/$(PROJECT) -name "*.cu")
 # TEST_SRCS are the test source files
+TEST_MAIN_SRC := src/$(PROJECT)/test/test_caffe_main.cpp
 TEST_SRCS := $(shell find src/$(PROJECT) -name "test_*.cpp")
+TEST_SRCS := $(filter-out $(TEST_MAIN_SRC), $(TEST_SRCS))
 GTEST_SRC := src/gtest/gtest-all.cpp
 # TEST_HDRS are the test header files
 TEST_HDRS := $(shell find src/$(PROJECT) -name "test_*.hpp")
@@ -32,9 +34,21 @@ TOOL_SRCS := $(shell find tools -name "*.cpp")
 EXAMPLE_SRCS := $(shell find examples -name "*.cpp")
 # PROTO_SRCS are the protocol buffer definitions
 PROTO_SRCS := $(wildcard src/$(PROJECT)/proto/*.proto)
+# NONGEN_CXX_SRCS includes all source/header files except those generated
+# automatically (e.g., by proto).
+NONGEN_CXX_SRCS := $(shell find \
+	src/$(PROJECT) \
+	include/$(PROJECT) \
+	python/$(PROJECT) \
+	matlab/$(PROJECT) \
+	examples \
+	tools \
+	-name "*.cpp" -or -name "*.hpp" -or -name "*.cu" -or -name "*.cuh")
+LINT_REPORT := $(BUILD_DIR)/cpp_lint.log
+FAILED_LINT_REPORT := $(BUILD_DIR)/cpp_lint.error_log
 # PY$(PROJECT)_SRC is the python wrapper for $(PROJECT)
-PY$(PROJECT)_SRC := python/$(PROJECT)/py$(PROJECT).cpp
-PY$(PROJECT)_SO := python/$(PROJECT)/py$(PROJECT).so
+PY$(PROJECT)_SRC := python/$(PROJECT)/_$(PROJECT).cpp
+PY$(PROJECT)_SO := python/$(PROJECT)/_$(PROJECT).so
 # MAT$(PROJECT)_SRC is the matlab wrapper for $(PROJECT)
 MAT$(PROJECT)_SRC := matlab/$(PROJECT)/mat$(PROJECT).cpp
 MAT$(PROJECT)_SO := matlab/$(PROJECT)/$(PROJECT)
@@ -62,6 +76,7 @@ GTEST_OBJ := $(addprefix $(BUILD_DIR)/, ${GTEST_SRC:.cpp=.o})
 TOOL_BINS := ${TOOL_OBJS:.o=.bin}
 EXAMPLE_BINS := ${EXAMPLE_OBJS:.o=.bin}
 TEST_BINS := ${TEST_OBJS:.o=.testbin}
+TEST_ALL_BIN := $(BUILD_DIR)/src/$(PROJECT)/test/test_all.testbin
 
 ##############################
 # Derive include and lib directories
@@ -73,8 +88,13 @@ MKL_LIB_DIR := $(MKL_DIR)/lib $(MKL_DIR)/lib/intel64
 
 INCLUDE_DIRS += ./src ./include $(CUDA_INCLUDE_DIR) $(MKL_INCLUDE_DIR)
 LIBRARY_DIRS += $(CUDA_LIB_DIR) $(MKL_LIB_DIR)
-LIBRARIES := cudart cublas curand mkl_rt pthread \
-	glog protobuf leveldb snappy boost_system \
+LIBRARIES := cudart cublas curand \
+	mkl_rt \
+	pthread \
+	glog protobuf leveldb \
+	snappy \
+	boost_system \
+	hdf5_hl hdf5 \
 	opencv_core opencv_highgui opencv_imgproc
 PYTHON_LIBRARIES := boost_python python2.7
 WARNINGS := -Wall
@@ -90,7 +110,8 @@ PYTHON_LDFLAGS := $(LDFLAGS) $(foreach library,$(PYTHON_LIBRARIES),-l$(library))
 ##############################
 # Define build targets
 ##############################
-.PHONY: all init test clean linecount tools examples py mat distribute py$(PROJECT) mat$(PROJECT) proto
+.PHONY: all init test clean linecount lint tools examples py mat distribute \
+        py$(PROJECT) mat$(PROJECT) proto runtest
 
 all: init $(NAME) $(STATIC_NAME) tools examples
 	@echo $(CXX_OBJS)
@@ -105,7 +126,18 @@ init:
 linecount: clean
 	cloc --read-lang-def=$(PROJECT).cloc src/$(PROJECT)/
 
-test: init $(TEST_BINS)
+lint: $(LINT_REPORT)
+
+$(LINT_REPORT): $(NONGEN_CXX_SRCS)
+	@ mkdir -p $(BUILD_DIR)
+	@ (python ./scripts/cpp_lint.py $(NONGEN_CXX_SRCS) > $(LINT_REPORT) 2>&1 \
+		&& (rm -f $(FAILED_LINT_REPORT); echo "No lint errors!")) || ( \
+			mv $(LINT_REPORT) $(FAILED_LINT_REPORT); \
+			grep -v "^Done processing " $(FAILED_LINT_REPORT); \
+			echo "Found 1 or more lint errors; see log at $(FAILED_LINT_REPORT)"; \
+			exit 1)
+
+test: init $(TEST_BINS) $(TEST_ALL_BIN)
 
 tools: init $(TOOL_BINS)
 
@@ -135,11 +167,14 @@ $(STATIC_NAME): init $(PROTO_OBJS) $(OBJS)
 	ar rcs $(STATIC_NAME) $(PROTO_OBJS) $(OBJS)
 	@echo
 
-runtest: test
-	for testbin in $(TEST_BINS); do $$testbin $(TEST_GPUID); done
+runtest: $(TEST_ALL_BIN)
+	$(TEST_ALL_BIN) $(TEST_GPUID)
 
 $(TEST_BINS): %.testbin : %.o $(GTEST_OBJ) $(STATIC_NAME) $(TEST_HDRS)
-	$(CXX) $< $(GTEST_OBJ) $(STATIC_NAME) -o $@ $(CXXFLAGS) $(LDFLAGS) $(WARNINGS)
+	$(CXX) $(TEST_MAIN_SRC) $< $(GTEST_OBJ) $(STATIC_NAME) -o $@ $(CXXFLAGS) $(LDFLAGS) $(WARNINGS)
+
+$(TEST_ALL_BIN): $(GTEST_OBJ) $(STATIC_NAME) $(TEST_OBJS)
+	$(CXX) $(TEST_MAIN_SRC) $(TEST_OBJS) $(GTEST_OBJ) $(STATIC_NAME) -o $(TEST_ALL_BIN) $(CXXFLAGS) $(LDFLAGS) $(WARNINGS)
 
 $(TOOL_BINS): %.bin : %.o $(STATIC_NAME)
 	$(CXX) $< $(STATIC_NAME) -o $@ $(CXXFLAGS) $(LDFLAGS) $(WARNINGS)

README.md

@@ -22,8 +22,8 @@ line of code: `Caffe::set_mode(Caffe::CPU)`.
 Even in CPU mode, computing predictions on an image takes only 20 ms when images
 are processed in batch mode.
 
+* [Caffe introductory presentation](https://www.dropbox.com/s/10fx16yp5etb8dv/caffe-presentation.pdf)
 * [Installation instructions](http://caffe.berkeleyvision.org/installation.html)
-* [Caffe presentation](https://docs.google.com/presentation/d/1lzyXMRQFlOYE2Jy0lCNaqltpcCIKuRzKJxQ7vCuPRc8/edit?usp=sharing) at the Berkeley Vision Group meeting
 
 \* When measured with the [SuperVision](http://www.image-net.org/challenges/LSVRC/2012/supervision.pdf) model that won the ImageNet Large Scale Visual Recognition Challenge 2012.
 

docs/cifar10.md

@@ -0,0 +1,95 @@
+---
+layout: default
+title: Caffe
+---
+
+Alex's CIFAR-10 tutorial, Caffe style
+=====================================
+
+Alex Krizhevsky's [cuda-convnet](https://code.google.com/p/cuda-convnet/) details the model definitions, parameters, and training procedure for good performance on CIFAR-10. This example reproduces his results in Caffe.
+
+We will assume that you have Caffe successfully compiled. If not, please refer to the [Installation page](installation.html). In this tutorial, we will assume that your caffe installation is located at `CAFFE_ROOT`.
+
+We thank @chyojn for the pull request that defined the model schemas and solver configurations.
+
+*This example is a work-in-progress. It would be nice to further explain details of the network and training choices and benchmark the full training.*
+
+Prepare the Dataset
+-------------------
+
+You will first need to download and convert the data format from the [CIFAR-10 website](http://www.cs.toronto.edu/~kriz/cifar.html). To do this, simply run the following commands:
+
+    cd $CAFFE_ROOT/data/cifar10
+    ./get_cifar10.sh
+    cd $CAFFE_ROOT/examples/cifar10
+    ./create_cifar10.sh
+
+If it complains that `wget` or `gunzip` are not installed, you need to install them respectively. After running the script there should be the dataset, `./cifar10-leveldb`, and the data set image mean `./mean.binaryproto`.
+
+The Model
+---------
+
+The CIFAR-10 model is a CNN that composes layers of convolution, pooling, rectified linear unit (ReLU) nonlinearities, and local contrast normalization with a linear classifier on top of it all. We have defined the model in the `CAFFE_ROOT/examples/cifar10` directory's `cifar10_quick_train.prototxt`.
+
+Training and Testing the "Quick" Model
+--------------------------------------
+
+Training the model is simple after you have written the network definition protobuf and solver protobuf files. Simply run `train_quick.sh`, or the following command directly:
+
+    cd $CAFFE_ROOT/examples/cifar10
+    ./train_quick.sh
+
+`train_quick.sh` is a simple script, so have a look inside. `GLOG_logtostderr=1` is the google logging flag that prints all the logging messages directly to stderr. The main tool for training is `train_net.bin`, with the solver protobuf text file as its argument.
+
+When you run the code, you will see a lot of messages flying by like this:
+
+    I0317 21:52:48.945710 2008298256 net.cpp:74] Creating Layer conv1
+    I0317 21:52:48.945716 2008298256 net.cpp:84] conv1 <- data
+    I0317 21:52:48.945725 2008298256 net.cpp:110] conv1 -> conv1
+    I0317 21:52:49.298691 2008298256 net.cpp:125] Top shape: 100 32 32 32 (3276800)
+    I0317 21:52:49.298719 2008298256 net.cpp:151] conv1 needs backward computation.
+
+These messages tell you the details about each layer, its connections and its output shape, which may be helpful in debugging. After the initialization, the training will start:
+
+    I0317 21:52:49.309370 2008298256 net.cpp:166] Network initialization done.
+    I0317 21:52:49.309376 2008298256 net.cpp:167] Memory required for Data 23790808
+    I0317 21:52:49.309422 2008298256 solver.cpp:36] Solver scaffolding done.
+    I0317 21:52:49.309447 2008298256 solver.cpp:47] Solving CIFAR10_quick_train
+
+Based on the solver setting, we will print the training loss function every 100 iterations, and test the network every 500 iterations. You will see messages like this:
+
+    I0317 21:53:12.179772 2008298256 solver.cpp:208] Iteration 100, lr = 0.001
+    I0317 21:53:12.185698 2008298256 solver.cpp:65] Iteration 100, loss = 1.73643
+    ...
+    I0317 21:54:41.150030 2008298256 solver.cpp:87] Iteration 500, Testing net
+    I0317 21:54:47.129461 2008298256 solver.cpp:114] Test score #0: 0.5504
+    I0317 21:54:47.129500 2008298256 solver.cpp:114] Test score #1: 1.27805
+
+For each training iteration, `lr` is the learning rate of that iteration, and `loss` is the training function. For the output of the testing phase, **score 0 is the accuracy**, and **score 1 is the testing loss function**.
+
+And after making yourself a cup of coffee, you are done!
+
+    I0317 22:12:19.666914 2008298256 solver.cpp:87] Iteration 5000, Testing net
+    I0317 22:12:25.580330 2008298256 solver.cpp:114] Test score #0: 0.7533
+    I0317 22:12:25.580379 2008298256 solver.cpp:114] Test score #1: 0.739837
+    I0317 22:12:25.587262 2008298256 solver.cpp:130] Snapshotting to cifar10_quick_iter_5000
+    I0317 22:12:25.590215 2008298256 solver.cpp:137] Snapshotting solver state to cifar10_quick_iter_5000.solverstate
+    I0317 22:12:25.592813 2008298256 solver.cpp:81] Optimization Done.
+
+Our model achieved ~75% test accuracy. The model parameters are stored in binary protobuf format in
+
+    cifar10_quick_iter_5000
+
+which is ready-to-deploy in CPU or GPU mode! Refer to the `CAFFE_ROOT/examples/cifar10/cifar10_quick.prototxt` for the deployment model definition that can be called on new data.
+
+Why train on a GPU?
+-------------------
+
+CIFAR-10, while still small, has enough data to make GPU training attractive.
+
+To compare CPU vs. GPU training speed, simply change one line in all the `cifar*solver.prototxt`:
+
+    # solver mode: 0 for CPU and 1 for GPU
+    solver_mode: 0
+
+and you will be using CPU for training.

docs/development.md

@@ -9,7 +9,7 @@ Developing & Contributing
 Caffe is developed with active participation of the community by the [Berkeley Vision and Learning Center](http://bvlc.eecs.berkeley.edu/).
 We welcome all contributions!
 
-The [contributing workflow](https://github.com/BVLC/caffe#contributing) is explained in the README. These guidelines cover development practices in Caffe. This is a work-in-progress.
+The [contributing workflow](https://github.com/BVLC/caffe#development) is explained in the README. These guidelines cover development practices in Caffe. This is a work-in-progress.
 
 **Development Flow**
 
@@ -36,6 +36,18 @@ We'd appreciate your contribution to the documentation effort!
 
 **Testing**: run `make runtest` to check the project tests. New code requires new tests. Pull requests that fail tests will not be accepted.
 
+The `googletest` framework we use provides many additional options, which you can access by running the test binaries directly. One of the more useful options is `--gtest_filter`, which allows you to filter tests by name:
+
+    # run all tests with CPU in the name
+    build/src/caffe/test/test_all.testbin --gtest_filter='*CPU*'
+
+    # run all tests without GPU in the name (note the leading minus sign)
+    build/src/caffe/test/test_all.testbin --gtest_filter=-'*GPU*'
+
+To get a list of all options `googletest` provides, simply pass the `--help` flag:
+
+    build/src/caffe/test/test_all.testbin --help
+
 **Style**
 
 - Follow [Google C++ style](http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml) and [Google python style](http://google-styleguide.googlecode.com/svn/trunk/pyguide.html) + [PEP 8](http://legacy.python.org/dev/peps/pep-0008/).

docs/getting_pretrained_models.md

@@ -0,0 +1,17 @@
+---
+layout: default
+---
+
+# Pre-trained models
+
+[BVLC](http://bvlc.eecs.berkeley.edu) aims to provide a variety of high quality pre-trained models.
+Note that unlike Caffe itself, these models are licensed for **academic research / non-commercial use only**.
+If you have any questions, please get in touch with us.
+
+This page will be updated as more models become available.
+
+### ImageNet
+
+Our reference implementation of the AlexNet model trained on ILSVRC-2012 can be downloaded (232.57MB) by running `examples/imagenet/get_caffe_reference_imagenet_model.sh` from the Caffe root directory.
+
+Additionally, you will probably eventually need some auxiliary data (mean image, synset list, etc.): run `data/ilsvrc12/get_ilsvrc_aux.sh` from the root directory to obtain it.