[WIP] R 3.4 recommendations + Benchmark/Parameter Notes (#511)

* Update to R 3.4 and Performance Note

* Add benchmark docs

* Readme.md does not exist fix

R-package/README.md

@@ -61,11 +61,37 @@ SHLIB_OPENMP_FFLAGS = -fopenmp
 EOF
 ```
 
-Note: for `LDFLAGS=-L/usr/local/Cellar/gcc/6.3.0/lib` and `CPPFLAGS=-I/usr/local/Cellar/gcc/6.3.0/include`, you may need to change `6.3.0` to your gcc version.
+Note:
+
+* For `LDFLAGS=-L/usr/local/Cellar/gcc/6.3.0/lib` and `CPPFLAGS=-I/usr/local/Cellar/gcc/6.3.0/include`, you may need to change `6.3.0` to your gcc version.
+* For `gcc-6` and `g++-6`, you may need to change to your gcc version (like `gcc-7` and `g++7` if using gcc with version 7).
+* For `CXX1X`, if you are using R 3.4 or a more recent version, you must change it to `CXX11`.
 
 To check your LightGBM installation, the test is identical to Linux/Windows versions (check the test provided just before OSX Installation part)
 
+Performance note
+------------
+
+With `gcc`, it is recommended to use `-O3 -mtune=native` instead of the default `-O2 -mtune=core2` by modifying the appropriate file (`Makeconf` or `Makevars`) if you want to achieve maximum speed.
+
+Benchmark example using Intel Ivy Bridge CPU on 1M x 1K dataset:
+
+| Compilation Flag | Performance Index |
+| --- | ---: |
+| `-O2 -mtune=core2` | 100.00% |
+| `-O2 -mtune=native` | 100.90% |
+| `-O3 -mtune=native` | 102.78% |
+| `-O3 -ffast-math -mtune=native` | 100.64% |
+
 Examples
 ------------
 
-* Please visit [demo](demo).
+Please visit [demo](demo):
+
+* [Basic walkthrough of wrappers](demo/basic_walkthrough.R)
+* [Boosting from existing prediction](demo/boost_from_prediction.R)
+* [Early Stopping](demo/early_stopping.R)
+* [Cross Validation](demo/cross_validation.R)
+* [Multiclass Training/Prediction](demo/multiclass.R)
+* [Leaf (in)Stability](demo/leaf_stability.R)
+* [Weight-Parameter Adjustment Relationship](demo/weight_param.R)

README.md

@@ -46,9 +46,9 @@ To get started, please follow the [Installation Guide](https://github.com/Micros
 * [**Examples**](https://github.com/Microsoft/LightGBM/tree/master/examples)
 * [**Features**](https://github.com/Microsoft/LightGBM/wiki/Features)
 * [**Parallel Learning Guide**](https://github.com/Microsoft/LightGBM/wiki/Parallel-Learning-Guide)
-* [**GPU Learning Tutorial**](./docs/GPU-Tutorial.md)
+* [**GPU Learning Tutorial**](https://github.com/Microsoft/LightGBM/blob/master/docs/GPU-Tutorial.md)
 * [**Configuration**](https://github.com/Microsoft/LightGBM/wiki/Configuration)
-* [**Document Indexer**](https://github.com/Microsoft/LightGBM/blob/master/docs/Readme.md)
+* [**Document Indexer**](https://github.com/Microsoft/LightGBM/blob/master/docs/README.md)
 
 How to Contribute
 -----------------

docs/gcc-tips.Rmd

@@ -0,0 +1,35 @@
+# Recommendations when using gcc
+
+It is recommended to use `-O3 -mtune=native` to achieve maximum speed during LightGBM training.
+
+Using Intel Ivy Bridge CPU on 1M x 1K Bosch dataset, the performance increases as follow:
+
+| Compilation Flag | Performance Index |
+| --- | ---: |
+| `-O2 -mtune=core2` | 100.00% |
+| `-O2 -mtune=native` | 100.90% |
+| `-O3 -mtune=native` | 102.78% |
+| `-O3 -ffast-math -mtune=native` | 100.64% |
+
+You can find more details on the experimentation below:
+
+* [Laurae++/Benchmarks](https://sites.google.com/view/lauraepp/benchmarks)
+* [Laurae2/gbt_benchmarks](https://github.com/Laurae2/gbt_benchmarks)
+* [Laurae's Benchmark Master Data (Interactive)](https://public.tableau.com/views/gbt_benchmarks/Master-Data?:showVizHome=no)
+* [Kaggle Paris Meetup #12 Slides](https://drive.google.com/file/d/0B6qJBmoIxFe0ZHNCOXdoRWMxUm8/view)
+
+Some pictures below:
+
+![gcc table](https://cloud.githubusercontent.com/assets/9083669/26027337/c376e22e-380c-11e7-91bc-fe0a333c03e9.png)
+
+![gcc bars](https://cloud.githubusercontent.com/assets/9083669/26027338/d1caebcc-380c-11e7-864e-d704b39f1e63.png)
+
+![gcc chart](https://cloud.githubusercontent.com/assets/9083669/26027353/e1bdb866-380c-11e7-97b5-22c7eac349b2.png)
+
+![gcc comparison 1](https://cloud.githubusercontent.com/assets/9083669/26027401/c31f2f74-380d-11e7-857a-f5119791bed7.png)
+
+![gcc comparison 2](https://cloud.githubusercontent.com/assets/9083669/26027486/d7d7e72a-380e-11e7-86c3-ccbbf42a9c55.png)
+
+![gcc meetup 1](https://cloud.githubusercontent.com/assets/9083669/26027427/21b38f44-380e-11e7-9c95-05437782dd46.png)
+
+![gcc meetup 2](https://cloud.githubusercontent.com/assets/9083669/26027433/362be250-380e-11e7-8982-76ac167bcd3e.png)