update docs

docs/conf.py

@@ -380,6 +380,7 @@ _DEPRECATED_NAMES = set([
     'prediction_incorrect', 'huber_loss',
 
     # internal only
+    'SessionUpdate',
     'apply_default_prefetch',
     'average_grads',
     'aggregate_grads',

docs/tutorial/inference.md

@@ -21,10 +21,14 @@ You can use this predicate to choose a different code path in inference mode.
 
 ## Inference After Training
 
-Tensorpack is a training interface -- it doesn't care what happened after training.
-It saves models to standard checkpoint format.
-So you can build the graph for inference, load the checkpoint, and then use whatever deployment methods TensorFlow supports.
-But you'll need to read TF docs and __do it on your own__.
+Tensorpack is a training interface -- __it doesn't care what happened after training__.
+You have everything needed for inference or model diagnosis after
+training:
+1. The trained weights: tensorpack saves them in standard TF checkpoint format.
+2. The model: you've already written it yourself with TF symbolic functions.
+
+Therefore, you can build the graph for inference, load the checkpoint, and then use whatever deployment methods TensorFlow supports.
+And you'll need to read TF docs and __do it on your own__.
 
 ### Don't Use Training Metagraph for Inference
 

docs/tutorial/save-load.md

@@ -8,8 +8,11 @@ in TensorFlow checkpoint format.
 A TF checkpoint typically includes a `.data-xxxxx` file and a `.index` file.
 Both are necessary.
 
-`tf.train.NewCheckpointReader` is the best tool to parse TensorFlow checkpoint.
-We have two example scripts to demo its usage, but read [TF docs](https://www.tensorflow.org/api_docs/python/tf/train/NewCheckpointReader) for details.
+`tf.train.NewCheckpointReader` is the offical tool to parse TensorFlow checkpoint.
+Read [TF docs](https://www.tensorflow.org/api_docs/python/tf/train/NewCheckpointReader) for details.
+Tensorpack also provides some small tools to work with checkpoints, see 
+[documentation](../modules/tfutils.html#tensorpack.tfutils.varmanip.load_chkpt_vars)
+for details.
 
 [scripts/ls-checkpoint.py](../scripts/ls-checkpoint.py)
 demos how to print all variables and their shapes in a checkpoint.

examples/FasterRCNN/README.md

@@ -79,15 +79,15 @@ MaskRCNN results contain both box and mask mAP.
  | -        | -                                                                                                        | -                                                  | -               | -                                                                                                                                                                                                |
  | R50-C4   | 33.1                                                                                                     |                                                    | 18h             | <details><summary>super quick</summary>`MODE_MASK=False FRCNN.BATCH_PER_IM=64`<br/>`PREPROC.SHORT_EDGE_SIZE=600 PREPROC.MAX_SIZE=1024`<br/>`TRAIN.LR_SCHEDULE=[150000,230000,280000]` </details> |
  | R50-C4   | 36.6                                                                                                     | 36.5                                               | 44h             | <details><summary>standard</summary>`MODE_MASK=False` </details>                                                                                                                                 |
- | R50-FPN  | 37.4                                                                                                     | 37.9                                               | 30h             | <details><summary>standard</summary>`MODE_MASK=False MODE_FPN=True` </details>                                                                                                                                  |
- | R50-C4   | 38.2;33.3 [:arrow_down:](http://models.tensorpack.com/FasterRCNN/COCO-R50C4-MaskRCNN-Standard.npz)       | 37.8;32.8                                          | 49h             | <details><summary>standard</summary>`MODE_MASK=True` </details>                                                                                                                                                 |
- | R50-FPN  | 38.5;35.2 [:arrow_down:](http://models.tensorpack.com/FasterRCNN/COCO-R50FPN-MaskRCNN-Standard.npz)      | 38.6;34.5                                          | 32h             | <details><summary>standard</summary>`MODE_MASK=True MODE_FPN=True` </details>                                                                                                                                   |
- | R50-FPN  | 39.1;35.2                                                                                                | 38.6;34.5                                          | 32h             | <details><summary>better params</summary>`MODE_MASK=True MODE_FPN=True`<br/>`TEST.RESULT_SCORE_THRESH=1e-4`<br/>`FRCNN.BBOX_REG_WEIGHTS=[20,20,10,10]` </details>                                               |
- | R50-FPN  | 39.5;35.2                                                                                                | 39.5;34.4<sup>[2](#ft2)</sup>                      | 34h             | <details><summary>standard+ConvGNHead</summary>`MODE_MASK=True MODE_FPN=True`<br/>`FPN.FRCNN_HEAD_FUNC=fastrcnn_4conv1fc_gn_head` </details>                                                                    |
- | R50-FPN  | 40.0;36.2 [:arrow_down:](http://models.tensorpack.com/FasterRCNN/COCO-R50FPN-MaskRCNN-StandardGN.npz)    | 40.3;35.7                                          | 44h             | <details><summary>standard+GN</summary>`MODE_MASK=True MODE_FPN=True`<br/>`FPN.NORM=GN BACKBONE.NORM=GN`<br/>`FPN.FRCNN_HEAD_FUNC=fastrcnn_4conv1fc_gn_head`<br/>`FPN.MRCNN_HEAD_FUNC=maskrcnn_up4conv_gn_head` |
- | R101-C4  | 41.4;35.2 [:arrow_down:](http://models.tensorpack.com/FasterRCNN/COCO-R101C4-MaskRCNN-Standard.npz)      |                                                    | 63h             | <details><summary>standard</summary>`MODE_MASK=True `<br/>`BACKBONE.RESNET_NUM_BLOCK=[3,4,23,3]` </details>                                                                                                     |
- | R101-FPN | 40.4;36.6 [:arrow_down:](http://models.tensorpack.com/FasterRCNN/COCO-R101FPN-MaskRCNN-Standard.npz)     | 40.9;36.4                                          | 40h             | <details><summary>standard</summary>`MODE_MASK=True MODE_FPN=True`<br/>`BACKBONE.RESNET_NUM_BLOCK=[3,4,23,3]` </details>                                                                                        |
- | R101-FPN | 41.1;36.6 [:arrow_down:](http://models.tensorpack.com/FasterRCNN/COCO-R101FPN-MaskRCNN-BetterParams.npz) | 40.9;36.4                                          | 40h             | <details><summary>better params</summary>`MODE_MASK=True MODE_FPN=True`<br/>`BACKBONE.RESNET_NUM_BLOCK=[3,4,23,3]`<br/>`TEST.RESULT_SCORE_THRESH=1e-4`<br/>`FRCNN.BBOX_REG_WEIGHTS=[20,20,10,10]` </details>    |
+ | R50-FPN  | 37.4                                                                                                     | 37.9                                               | 29h             | <details><summary>standard</summary>`MODE_MASK=False MODE_FPN=True` </details>                                                                                                                   |
+ | R50-C4   | 38.2;33.3 [:arrow_down:](http://models.tensorpack.com/FasterRCNN/COCO-R50C4-MaskRCNN-Standard.npz)       | 37.8;32.8                                          | 49h             | <details><summary>standard</summary>this is the default </details>                                                                                                                               |
+ | R50-FPN  | 38.5;35.2 [:arrow_down:](http://models.tensorpack.com/FasterRCNN/COCO-R50FPN-MaskRCNN-Standard.npz)      | 38.6;34.5                                          | 30h             | <details><summary>standard</summary>`MODE_FPN=True` </details>                                                                                                                                   |
+ | R50-FPN  | 42.0;36.3                                                                                                |                                                    | 41h             | <details><summary>+Cascade</summary>`MODE_FPN=True FPN.CASCADE=True` </details>                                                                                                                  |
+ | R50-FPN  | 39.5;35.2                                                                                                | 39.5;34.4<sup>[2](#ft2)</sup>                      | 33h             | <details><summary>+ConvGNHead</summary>`MODE_FPN=True`<br/>`FPN.FRCNN_HEAD_FUNC=fastrcnn_4conv1fc_gn_head` </details>                                                                            |
+ | R50-FPN  | 40.0;36.2 [:arrow_down:](http://models.tensorpack.com/FasterRCNN/COCO-R50FPN-MaskRCNN-StandardGN.npz)    | 40.3;35.7                                          | 40h             | <details><summary>+GN</summary>`MODE_FPN=True`<br/>`FPN.NORM=GN BACKBONE.NORM=GN`<br/>`FPN.FRCNN_HEAD_FUNC=fastrcnn_4conv1fc_gn_head`<br/>`FPN.MRCNN_HEAD_FUNC=maskrcnn_up4conv_gn_head`         |
+ | R101-C4  | 41.4;35.2 [:arrow_down:](http://models.tensorpack.com/FasterRCNN/COCO-R101C4-MaskRCNN-Standard.npz)      |                                                    | 60h             | <details><summary>standard</summary>`BACKBONE.RESNET_NUM_BLOCK=[3,4,23,3]` </details>                                                                                                            |
+ | R101-FPN | 40.4;36.6 [:arrow_down:](http://models.tensorpack.com/FasterRCNN/COCO-R101FPN-MaskRCNN-Standard.npz)     | 40.9;36.4                                          | 38h             | <details><summary>standard</summary>`MODE_FPN=True`<br/>`BACKBONE.RESNET_NUM_BLOCK=[3,4,23,3]` </details>                                                                                        |
+ | R101-FPN | 41.1;36.6 [:arrow_down:](http://models.tensorpack.com/FasterRCNN/COCO-R101FPN-MaskRCNN-BetterParams.npz) | 40.9;36.4                                          | 38h             | <details><summary>better params</summary>`MODE_FPN=True`<br/>`BACKBONE.RESNET_NUM_BLOCK=[3,4,23,3]`<br/>`TEST.RESULT_SCORE_THRESH=1e-4`<br/>`FRCNN.BBOX_REG_WEIGHTS=[20,20,10,10]` </details>    |
 
  <a id="ft1">1</a>: Here we comapre models that have identical training & inference cost between the two implementation. However their numbers are different due to many small implementation details.
 

tensorpack/tfutils/varmanip.py

 # -*- coding: utf-8 -*-
 # File: varmanip.py
 
-
 import six
 import os
 import pprint
 import tensorflow as tf
 import numpy as np
-from ..utils.develop import deprecated
 from ..utils import logger
 from .common import get_op_tensor_name
 
@@ -50,7 +48,7 @@ class SessionUpdate(object):
     @staticmethod
     def load_value_to_var(var, val, strict=False):
         """
-        Call `var.load(val)` with the default session.
+        Call `var.load(val)` with the default session, with some type checks.
 
         Args:
             var (tf.Variable):
@@ -111,7 +109,7 @@ class SessionUpdate(object):
 def dump_session_params(path):
     """
     Dump value of all TRAINABLE + MODEL variables to a dict, and save as
-    npz format (loadable by :class:`DictRestore`).
+    npz format (loadable by :func:`sessinit.get_model_loader`).
 
     Args:
         path(str): the file name to save the parameters. Must ends with npz.
@@ -203,11 +201,6 @@ def load_chkpt_vars(model_path):
     return result
 
 
-@deprecated("Renamed to 'load_chkpt_vars!'", "2018-04-20")
-def dump_chkpt_vars(model_path):
-    return load_chkpt_vars(model_path)
-
-
 def is_training_name(name):
     """
     **Guess** if this variable is only used in training.