Merge remote-tracking branch 'origin/master'

.gitignore

@@ -8,3 +8,109 @@ others/*
 *.log
 *.tar
 *.pth
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+>>>>>>> origin/master

LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation. All rights reserved.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

README.md

@@ -1,27 +1,27 @@
 ## Improving Generalization via Scalable Neighborhood Component Analysis
 
-This repo constains the pytorch implementation for the ECCV2018 paper [(arxiv)](https://arxiv.org/pdf/.pdf).
-The project is about deep learning feature representations optimized for
-nearest neighbor classifiers, which may generalize to new object categories.
+This repo constains the pytorch implementation for the ECCV 2018 paper [(arxiv)](https://arxiv.org/pdf/.pdf).
+We use deep networks to learn feature representations optimized for nearest neighbor classifiers, which could generalize better for new object categories.
+We re-investigate the [Neighborhood Component Analysis (NCA)](http://www.cs.toronto.edu/~fritz/absps/nca.pdf), and we propose a technique to make it 
+scalable to deep networks and large-scale datasets.
 
-Much of code is borrowed from the previous [unsupervised learning project](https://arxiv.org/pdf/1805.01978.pdf).
+Much of code is extened from the previous [unsupervised learning project](https://arxiv.org/pdf/1805.01978.pdf).
 Please refer to [this repo](https://github.com/zhirongw/lemniscate.pytorch) for more details.
 
 
 ## Pretrained Model
 
-Currently, we provide 3 pretrained ResNet models.
+Currently, we provide three pretrained ResNet models.
 Each release contains the feature representation of all ImageNet training images (600 mb) and model weights (100-200mb).
-You can also get these representations by forwarding the network for the entire ImageNet images.
 
 - [ResNet 18](http://zhirongw.westus2.cloudapp.azure.com/models/snca_resnet18.pth.tar) (top 1 accuracy 70.59%)
 - [ResNet 34](http://zhirongw.westus2.cloudapp.azure.com/models/snca_resnet34.pth.tar) (top 1 accuracy 74.41%)
 - [ResNet 50](http://zhirongw.westus2.cloudapp.azure.com/models/snca_resnet50.pth.tar) (top 1 accuracy 76.57%)
 
-## Nearest Neighbor
+## Nearest Neighbors
 
 Please follow [this link](http://zhirongw.westus2.cloudapp.azure.com/nn.html) for a list of nearest neighbors on ImageNet.
-Results are visualized from our ResNet50 feature, compared with baseline ResNet50 feature, raw image features and supervised features.
+Results are visualized from our ResNet50 feature, compared with baseline ResNet50 feature, raw image features and previous unsupervised features.
 First column is the query image, followed by 20 retrievals ranked by the similarity.
 
 ## Usage
@@ -29,9 +29,9 @@ First column is the query image, followed by 20 retrievals ranked by the similar
 Our code extends the pytorch implementation of imagenet classification in [official pytorch release](https://github.com/pytorch/examples/tree/master/imagenet). 
 Please refer to the official repo for details of data preparation and hardware configurations.
 
-- install python2 and [pytorch=0.3](http://pytorch.org)
+- install python2 and [pytorch>=0.4](http://pytorch.org)
 
-- clone this repo: `git clone https://github.com/zhirongw/snca.pytorch`
+- clone this repo: `git clone https://github.com/Microsoft/snca.pytorch`
 
 - Training on ImageNet:
 
@@ -43,9 +43,18 @@ Please refer to the official repo for details of data preparation and hardware c
 
   `python main.py DATAPATH --arch resnet18 --resume input_model.pth.tar -e` runs testing with default K=30 neighbors.
 
+- Memory Consumption and Computation Issues
+
+  Memory consumption is more of an issue than computation time.
+  Currently, the implementation of nca module is not paralleled across multiple GPUs.
+  Hence, the first GPU will consume much more memory than the others.
+  For example, when training a ResNet18 network, GPU 0 will consume 11GB memory, while the others each takes 2.5GB.
+  You will need to set the Caffe style "iter_size" for training deep networks.
+  Our released models are trained with V100 machines 
+  
 - Training on CIFAR10:
 
-  `python cifar.py --nce-t 0.05 --lr 0.1`
+  `python cifar.py --temperature 0.05 --lr 0.1`
 
 
 ## Citation
@@ -64,3 +73,17 @@ For any questions, please feel free to reach
 ```
 Zhirong Wu: xavibrowu@gmail.com
 ```
+
+# Contributing
+
+This project welcomes contributions and suggestions.  Most contributions require you to agree to a
+Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
+the rights to use your contribution. For details, visit https://cla.microsoft.com.
+
+When you submit a pull request, a CLA-bot will automatically determine whether you need to provide
+a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions
+provided by the bot. You will only need to do this once across all repos using our CLA.
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
+contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.