Document improvements (facebookresearch#459)

Summary: Pull Request resolved: facebookresearch#459 Reviewed By: prigoyal Differential Revision: D31935819 Pulled By: iseessel fbshipit-source-id: 2597dede102e2faf52cade370e76a53b0ce52af7
johnnynunez · Oct 26, 2021 · db500ec · db500ec
1 parent 8901487
commit db500ec
Show file tree

Hide file tree

Showing 55 changed files with 930 additions and 367 deletions.
diff --git a/INSTALL.md b/INSTALL.md
@@ -4,12 +4,12 @@ Our installation is simple and we provide pre-built binaries (pip, conda) and al
 
 ## Table of Contents
 - [Requirements](#requirements)
-- [Installing VISSL from pre-built binaries](#Installing-VISSL-from-pre-built-binaries)
-   - [Install VISSL conda package](#Install-VISSL-conda-package)
-   - [Install VISSL pip package](#Install-VISSL-pip-package)
 - [Installing VISSL from source](#Installing-VISSL-from-source)
     - [Install from source in PIP environment](#Install-from-source-in-PIP-environment)
     - [Install from source in Conda environment](#Install-from-source-in-Conda-environment)
+- [Installing VISSL from pre-built binaries](#Installing-VISSL-from-pre-built-binaries)
+   - [Install VISSL conda package](#Install-VISSL-conda-package)
+   - [Install VISSL pip package](#Install-VISSL-pip-package)
 
 
 ## Requirements
@@ -23,71 +23,7 @@ At a high level, project requires following system dependencies.
 - CUDA (must be a version supported by the pytorch version)
 - OpenCV (optional)
 
-## Installing VISSL from pre-built binaries
-
-### Install VISSL conda package
-
-This assumes you have CUDA 10.2.
-
-```bash
-conda create -n vissl python=3.8
-conda activate vissl
-conda install -c pytorch pytorch=1.7.1 torchvision cudatoolkit=10.2
-conda install -c vissl -c iopath -c conda-forge -c pytorch -c defaults apex vissl
-```
-
-The package also contains code for the fairscale and ClassyVision libraries. Ensure you do not have them installed separately.
-
-For other versions of PyTorch, Python, CUDA, please modify the above instructions with the
-desired version. VISSL provides Apex packages for all combinations of pytorch, python and compatible cuda.
-
-### Install VISSL pip package
-
-This example is with pytorch 1.5.1 and cuda 10.1. Please modify the PyTorch version, cuda version and accordingly apex version below for the desired settings.
-
-#### Step 1: Create Virtual environment (pip)
-```bash
-python3 -m venv ~/venv
-. ~/venv/bin/activate
-```
-
-#### Step 2: Install PyTorch, OpenCV and APEX (pip)
-
-- We use PyTorch=1.5.1 with CUDA 10.1 in the following instruction (user can chose their desired version).
-- There are several ways to install opencv, one possibility is as follows.
-- For APEX, we provide pre-built binary built with optimized C++/CUDA extensions provided by APEX.
-
-```bash
-pip install torch==1.5.1+cu101 torchvision==0.6.1+cu101 -f https://download.pytorch.org/whl/torch_stable.html
-pip install opencv-python
-pip install -f https://dl.fbaipublicfiles.com/vissl/packaging/apexwheels/py38_cu101_pyt151/download.html apex
-```
-
-Note that, for the APEX install, you need to get the versions of CUDA, PyTorch, and Python correct in the URL. We provide APEX versions with all possible combinations of Python, PyTorch, CUDA. Select the right APEX Wheels if you desire a different combination.
-
-On Google Colab, everything until this point is already set up. You install APEX there as follows.
-```
-import sys
-import torch
-version_str="".join([
-    f"py3{sys.version_info.minor}_cu",
-    torch.version.cuda.replace(".",""),
-    f"_pyt{torch.__version__[0:5:2]}"
-])
-!pip install -f https://dl.fbaipublicfiles.com/vissl/packaging/apexwheels/{version_str}/download.html apex
-```
-
-#### Step 3: Install VISSL
-
-```bash
-pip install vissl
-# verify installation
-python -c 'import vissl'
-```
-
-The package also contains code for the ClassyVision library. Ensure you do not have it installed separately.
-
-## Installing VISSL from source
+## Installing VISSL from source (recommended)
 The following instructions assume that you have desired CUDA version installed and working.
 
 ### Install from source in PIP environment
@@ -115,6 +51,10 @@ pip install -f https://dl.fbaipublicfiles.com/vissl/packaging/apexwheels/py37_cu
 ```bash
 # clone vissl repository
 cd $HOME && git clone --recursive https://github.com/facebookresearch/vissl.git && cd $HOME/vissl/
+# Optional, checkout stable v0.1.6 branch. While our docs are versioned, the tutorials
+# use v0.1.6 and the docs are more likely to be up-to-date.
+git checkout v0.1.6
+git checkout -b v0.1.6
 # install vissl dependencies
 pip install --progress-bar off -r requirements.txt
 pip install opencv-python
@@ -153,8 +93,71 @@ conda install -c vissl apex
 #### Step 4: Install VISSL
 Follow [step4 instructions from the PIP installation](#step-4-install-vissl)
 
-That's it! You are now ready to use this code.
+## Installing VISSL from pre-built binaries
+
+### Install VISSL conda package
+
+This assumes you have CUDA 10.2.
+
+```bash
+conda create -n vissl python=3.8
+conda activate vissl
+conda install -c pytorch pytorch=1.7.1 torchvision cudatoolkit=10.2
+conda install -c vissl -c iopath -c conda-forge -c pytorch -c defaults apex vissl
+```
+
+The package also contains code for the fairscale and ClassyVision libraries. Ensure you do not have them installed separately.
 
+For other versions of PyTorch, Python, CUDA, please modify the above instructions with the
+desired version. VISSL provides Apex packages for all combinations of pytorch, python and compatible cuda.
+
+### Install VISSL pip package
+
+This example is with pytorch 1.5.1 and cuda 10.1. Please modify the PyTorch version, cuda version and accordingly apex version below for the desired settings.
+
+#### Step 1: Create Virtual environment (pip)
+```bash
+python3 -m venv ~/venv
+. ~/venv/bin/activate
+```
+
+#### Step 2: Install PyTorch, OpenCV and APEX (pip)
+
+- We use PyTorch=1.5.1 with CUDA 10.1 in the following instruction (user can chose their desired version).
+- There are several ways to install opencv, one possibility is as follows.
+- For APEX, we provide pre-built binary built with optimized C++/CUDA extensions provided by APEX.
+
+```bash
+pip install torch==1.5.1+cu101 torchvision==0.6.1+cu101 -f https://download.pytorch.org/whl/torch_stable.html
+pip install opencv-python
+pip install -f https://dl.fbaipublicfiles.com/vissl/packaging/apexwheels/py38_cu101_pyt151/download.html apex
+```
+
+Note that, for the APEX install, you need to get the versions of CUDA, PyTorch, and Python correct in the URL. We provide APEX versions with all possible combinations of Python, PyTorch, CUDA. Select the right APEX Wheels if you desire a different combination.
+
+On Google Colab, everything until this point is already set up. You install APEX there as follows.
+```
+import sys
+import torch
+version_str="".join([
+    f"py3{sys.version_info.minor}_cu",
+    torch.version.cuda.replace(".",""),
+    f"_pyt{torch.__version__[0:5:2]}"
+])
+!pip install -f https://dl.fbaipublicfiles.com/vissl/packaging/apexwheels/{version_str}/download.html apex
+```
+
+#### Step 3: Install VISSL
+
+```bash
+pip install vissl
+# verify installation
+python -c 'import vissl'
+```
+
+The package also contains code for the ClassyVision library. Ensure you do not have it installed separately.
+
+That's it! You are now ready to use this code.
 
 
 ### Optional: Install Apex from source (common for both pip and conda)

diff --git a/configs/config/benchmark/instance_retrieval/eval_resnet_1gpu_copydays.yaml b/configs/config/benchmark/instance_retrieval/eval_resnet_1gpu_copydays.yaml
@@ -0,0 +1,53 @@
+# @package _global_
+config:
+  DISTRIBUTED:
+    NUM_PROC_PER_NODE: 1
+  MODEL:
+    FEATURE_EVAL_SETTINGS:
+      EVAL_MODE_ON: True
+      FREEZE_TRUNK_ONLY: True
+      EXTRACT_TRUNK_FEATURES_ONLY: True
+      SHOULD_FLATTEN_FEATS: false
+      LINEAR_EVAL_FEAT_POOL_OPS_MAP: [
+          ["res4", ["Identity", []]]
+      ]
+    TRUNK:
+      NAME: resnet
+      RESNETS:
+        DEPTH: 50
+    WEIGHTS_INIT:
+      ############################# OSS model ####################################
+      PARAMS_FILE: <your model weights>
+      STATE_DICT_KEY_NAME: classy_state_dict
+      ############ example settings for torchvision model rn50 ###################
+      # PARAMS_FILE: https://download.pytorch.org/models/resnet50-19c8e357.pth
+      # STATE_DICT_KEY_NAME: ""
+      # APPEND_PREFIX: "trunk.base_model._feature_blocks."
+  IMG_RETRIEVAL:
+    ############################# Dataset Information ####################################
+    EVAL_DATASET_NAME: copydays
+    TRAIN_DATASET_NAME: copydays/train
+    DATASET_PATH: <enter dataset path>
+    # Number of training samples to use. -1 uses all the samples in the dataset.
+    NUM_TRAINING_SAMPLES: -1
+    # Number of query samples to use. -1 uses all the samples in the dataset.
+    NUM_QUERY_SAMPLES: -1
+    # Number of database samples to use. -1 uses all the samples in the dataset.
+    NUM_DATABASE_SAMPLES: -1
+    # Sets data limits for the number of training, query, and database samples.
+    DEBUG_MODE: False
+    ############################# Data Processing Hypers ####################################
+    RESIZE_IMG: 224
+    TRAIN_PCA_WHITENING: True
+    N_PCA: 1024
+    FEATS_PROCESSING_TYPE: rmac  # l2 norm not recommended
+    SPATIAL_LEVELS: 3
+    # RN50 - res5
+    # N_PCA: 2048
+    # valid only for GeM pooling of features
+    GEM_POOL_POWER: 4.0
+    # Whether or not to apply L2 norm after the features have been post-processed.
+    # Normalization is heavily recommended based on experiments run.
+    NORMALIZE_FEATURES: True
+    # Whether or not to use distractor images.
+    USE_DISTRACTORS: True
diff --git a/docs/source/compatibility_libraries.rst b/docs/source/compatibility_libraries.rst
@@ -1,17 +1,17 @@
 Compatibility with Other Libraries
 ========================================
 
-- VISSL provides several helpful scripts to convert VISSL models to models that are compatible with other libraries like `Detectron2 <https://github.com/facebookresearch/detectron2>`_ and `ClassyVision <https://github.com/facebookresearch/ClassyVision>`_ compatible models.
+- VISSL provides several helpful scripts to convert VISSL models to models that are compatible with other libraries like `Detectron2 <https://github.com/facebookresearch/detectron2>`_ and `ClassyVision <https://github.com/facebookresearch/ClassyVision>`_.
 - VISSL also provides scripts to convert models from other sources like `Caffe2 models <https://github.com/facebookresearch/fair_self_supervision_benchmark/blob/master/MODEL_ZOO.md>`_ in the `paper <https://arxiv.org/abs/1905.01235>`_ to VISSL compatible models.
-- `TorchVision <https://github.com/pytorch/vision/tree/main/torchvision/models>`_ models are directly compatible with VISSL and don't require any conversion.
+- `TorchVision <https://github.com/pytorch/vision/tree/main/torchvision/models>`_ models trunks are directly compatible with VISSL and don't require any conversion.
 
 Converting Models VISSL -> {Detectron2, ClassyVision, TorchVision}
----------------------------------------------------------------
+-------------------------------------------------------------------
 We provide scripts to convert VISSL models to `Detectron2 <https://github.com/facebookresearch/detectron2>`_ and `ClassyVision <https://github.com/facebookresearch/ClassyVision>`_ compatible models.
 
 Converting to Detectron2
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-All the ResNe(X)t models in VISSL can be converted to Detectron2 weights using following command:
+All the ResNe(X)t models in VISSL can be converted to Detectron2 weights using the following command:
 
 .. code-block:: bash
 
@@ -24,7 +24,7 @@ All the ResNe(X)t models in VISSL can be converted to Detectron2 weights using f
 
 Converting to ClassyVision
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-All the ResNe(X)t models in VISSL can be converted to Classy Vision weights using following command:
+All the ResNe(X)t models in VISSL can be converted to Classy Vision weights using the following command:
 
 .. code-block:: bash
 
@@ -36,7 +36,7 @@ All the ResNe(X)t models in VISSL can be converted to Classy Vision weights usin
 
 Converting to TorchVision
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-All the ResNe(X)t models in VISSL can be converted to Torchvision weights using following command:
+All the ResNe(X)t models in VISSL can be converted to Torchvision weights using the following command:
 
 .. code-block:: bash
 

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -86,6 +86,7 @@
     "sphinx.ext.githubpages",
     "sphinx.ext.doctest",
     "sphinx.ext.ifconfig",
+    "sphinx.ext.autosectionlabel",
     "sphinx_markdown_tables",
 ]
 

diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst
@@ -25,11 +25,11 @@ make sure to have a corresponding issue to discuss your motivation and proposals
 before sending a PR. We do not always accept new features, and we take the following
 factors into consideration:
 
-1. Whether the same feature can be achieved without modifying VISSL. VISSL is designed to be extensible so that it's easy to extend any modular component and train custom models. If some part is not as extensible, you can also bring up the issue to make it more extensible.
-2. Whether the feature is potentially useful to a large audience, or only to a small portion of users.
+1. Whether the same feature can be achieved without modifying VISSL. VISSL is designed to be extensible. As VISSL is a research library, we want to encourage modular components that are easy to extend. If some part is not as extensible as you would like, you can flag this.
+2. Whether the feature is useful to a larger audience or only to a small portion of users.
 3. Whether the proposed solution has a good design / interface.
-4. Whether the proposed solution adds extra mental/practical overhead to users who don't need such feature.
-5. Whether the proposed solution breaks existing APIs.
+4. Whether the proposed solution adds extra mental/practical overhead to users who don't need such a feature.
+5. Whether the proposed solution breaks any existing APIs.
 
 When sending a PR, please do:
 
@@ -38,8 +38,9 @@ When sending a PR, please do:
 3. If you've added code that should be tested, add tests.
 4. If you've changed APIs, update the documentation.
 5. Ensure the test suite passes. Follow `cpu test instructions <https://github.com/facebookresearch/vissl/blob/main/tests/README.md>`_ and `integration tests <https://github.com/facebookresearch/vissl/blob/main/dev/run_quick_tests.sh>`_.
-6. Make sure your code follows our coding practices (see next section).
-7. If you haven't already, complete the Contributor License Agreement ("CLA").
+6. Please run the `linter <https://github.com/facebookresearch/vissl/tree/main/dev#option-3-use-python-devlint_commitpy--a>`_.
+7. Make sure your code follows our coding practices (see next section).
+8. If you haven't already, complete the Contributor License Agreement ("CLA").
 
 Coding Style
 ------------------------

diff --git a/docs/source/evaluations/feature_eval_settings.md b/docs/source/evaluations/feature_eval_settings.md
@@ -215,6 +215,9 @@ MODEL:
     NAME: resnet
     RESNETS:
       DEPTH: 50
+EXTRACT_FEATURES:
+  OUTPUT_DIR: ""
+  CHUNK_THRESHOLD: 0
 ```
 
 ### Extract features of the trunk output
@@ -230,6 +233,9 @@ MODEL:
     NAME: resnet
     RESNETS:
       DEPTH: 50
+EXTRACT_FEATURES:
+  OUTPUT_DIR: ""
+  CHUNK_THRESHOLD: 0
 ```
 
 ### Extract features of the model head output (self-supervised head)
@@ -249,9 +255,11 @@ MODEL:
       ["mlp", {"dims": [2048, 2048], "use_relu": True}],
       ["mlp", {"dims": [2048, 128]}],
     ]
+EXTRACT_FEATURES:
+  OUTPUT_DIR: ""
+  CHUNK_THRESHOLD: 0
 ```
 
 ## Full finetuning
 
-Since this only requires to initialize the model from the pre-trained model weights, there's
-no need for the `FEATURE_EVAL_SETTINGS` params. Simply set `MODEL.WEIGHTS_INIT` params.
+Since this only requires to initialize the model from the pre-trained model weights, there's no need for the `FEATURE_EVAL_SETTINGS` params. Simply set the `MODEL.WEIGHTS_INIT` params.