update docs

docs/tutorial/save-load.md

@@ -51,10 +51,13 @@ You can also use
 [get_model_loader(filename)](../modules/tfutils.html#tensorpack.tfutils.sessinit.get_model_loader),
 a small helper which returns either a `SaverRestore` or a `DictRestore` based on the file name.
 
-Variable restoring is completely based on __exact name match__ between
-variables in the current graph and variables in the `session_init` initializer.
-Variables that appear in only one side will be printed as warning.
-Variables of the same name but incompatible shapes will cause error.
+Whatever you use in `session_init`, this is what happen during the loading:
+
+* Variable restoring is completely based on __exact name match__ between
+	variables in the current graph and variables in the `session_init` initializer.
+* Variables that appear in only one side will be printed as warning.
+* Variables of the same name but incompatible shapes will cause exceptions.
+  If you set `ignore_mismatch=True`, then such errors will only be printed as warnings.
 
 ## Transfer Learning
 

examples/FasterRCNN/BALLOON.md

@@ -26,7 +26,7 @@ wget http://models.tensorpack.com/FasterRCNN/COCO-MaskRCNN-R50FPN2x.npz
 ./train.py --config DATA.BASEDIR=~/data/balloon MODE_FPN=True \
 	"DATA.VAL=('balloon_val',)"  "DATA.TRAIN=('balloon_train',)" \
 	TRAIN.BASE_LR=1e-3 TRAIN.EVAL_PERIOD=0 "TRAIN.LR_SCHEDULE=[1000]" \
-	"PREPROC.TRAIN_SHORT_EDGE_SIZE=[600,1200]" TRAIN.CHECKPOINT_PERIOD=1 \
+	"PREPROC.TRAIN_SHORT_EDGE_SIZE=[600,1200]" TRAIN.CHECKPOINT_PERIOD=1 DATA.NUM_WORKERS=1 \
 	--load COCO-MaskRCNN-R50FPN2x.npz --logdir train_log/balloon
 ```
 

examples/FasterRCNN/NOTES.md

@@ -33,11 +33,6 @@ Data:
 
 	 See [BALLOON.md](BALLOON.md) for an example of fine-tuning on a different dataset.
 
-1. If you load a COCO-trained model on a different dataset, you may see error messages
-   complaining about unmatched number of categories for certain weights in the checkpoint.
-   You can either remove those weights in checkpoint, or rename them in the model.
-   See [tensorpack tutorial](https://tensorpack.readthedocs.io/tutorial/save-load.html) for more details.
-
 1. You can easily add more augmentations such as rotation, but be careful how a box should be
    augmented. The code now will always use the minimal axis-aligned bounding box of the 4 corners,
    which is probably not the optimal way.
@@ -86,8 +81,6 @@ Efficiency:
 
 Possible Future Enhancements:
 
-1. Define a better interface to load different datasets.
-
 1. Support batch>1 per GPU. Batching with inconsistent shapes is
    non-trivial to implement in TensorFlow.
 

tensorpack/libinfo.py

@@ -98,5 +98,5 @@ else:
 
 # These lines will be programatically read/write by setup.py
 # Don't touch them.
-__version__ = '0.9.7'
+__version__ = '0.9.7.1'
 __git_version__ = __version__

tensorpack/tfutils/sessinit.py

@@ -165,8 +165,11 @@ class SaverRestoreRelaxed(SaverRestore):
 
         It allows upcasting certain variables, or reshape certain
         variables when there is a mismatch that can be fixed.
+
+        When variable shape and value shape do not match, it will print a
+        warning but will not crash.
+
         Another advantage is that it doesn't add any new ops to the graph.
-        But it is also slower than :class:`SaverRestore`.
     """
     def _run_init(self, sess):
         logger.info(
@@ -196,7 +199,9 @@ class DictRestore(SessionInit):
         Args:
             variable_dict (dict): a dict of {name: value}
             ignore_mismatch (bool): ignore failures when the value and the
-                variable does not match.
+                variable does not match in their shapes.
+                If False, it will throw exception on such errors.
+                If True, it will only print a warning.
         """
         assert isinstance(variable_dict, dict), type(variable_dict)
         # use varname (with :0) for consistency
@@ -261,8 +266,10 @@ def get_model_loader(filename, ignore_mismatch=False):
 
     Args:
         filename (str): either a tensorflow checkpoint, or a npz file.
-        ignore_mismatch (bool): ignore failures when values in the file and
-            variables in the graph do not match.
+        ignore_mismatch (bool): ignore failures when the value and the
+            variable does not match in their shapes.
+            If False, it will throw exception on such errors.
+            If True, it will only print a warning.
 
     Returns:
         SessInit: either a :class:`DictRestore` (if name ends with 'npy/npz') or