docs update & StagingInputWrapper -> StagingInput

.github/ISSUE_TEMPLATE.md

 Bug Reports/Feature Requests/Usage Questions Only:
 
-Bug Reports:
+Bug Reports (including performance bug):
 Some part of code (either the library or examples) doesn't work as expected.
+Always include what you did, what you observed, what you expected.
 
 Feature Requests:
 1. Improve an existing feature.
 2. Add a new feature. Please note that, you can implement a lot of features by extending tensorpack
 	(See http://tensorpack.readthedocs.io/en/latest/tutorial/index.html#extend-tensorpack).
 	It may not have to be added to tensorpack unless you have a good reason.
-3. Note that we don't implement papers at other's requests.
+3. Note that we don't implement papers at others' requests.
 
 Usage Questions, e.g.:
 "How do I do [this specific thing] in tensorpack?"

CHANGES.md

@@ -10,10 +10,10 @@ TensorFlow itself also changed APIs before 1.0 and those are not listed here.
 
 + [2017/10/21]
 	tensorpack is gradually switching to a new Trainer API.
-	Compatibility is kept in most ways but not guaranteed.
+	The old API will keep working for a while.
 	To switch to new API, the easiest way is to:
 
-	1. `export TENSORPACK_TRAIN_API=v2`	(will be default in the future).
+	1. `export TENSORPACK_TRAIN_API=v2`	(will be default soon in the future).
 	2. Replace `SomeTrainer(config, ...).train()` with `launch_train_with_config(config, SomeTrainer(...))`.
 
 + [2017/10/18]

docs/conf.py

@@ -367,6 +367,7 @@ def autodoc_skip_member(app, what, name, obj, skip, options):
         'VisualQA',
         'huber_loss',
         'DumpTensor',
+        'StagingInputWrapper',
         'StepTensorPrinter'
         ]:
         return True

docs/tutorial/trainer.md

@@ -22,36 +22,31 @@ In other words, an "epoch" in tensorpack is the __default period to run callback
 
 ### Common Trainers
 
-<!--
-   -Most neural network training tasks are single-cost optimization.
-   -Tensorpack provides some trainer implementations for such tasks.
-   -These trainers will build the graph based on the given `ModelDesc`, and minimizes `ModelDesc.cost`.
-	 -->
-
-<!--
-   -To use trainers, pass a `TrainConfig` to configure them:
-   -
-   -```python
-   -config = TrainConfig(
-   -           model=MyModel()
-   -           dataflow=my_dataflow,
-   -           # data=my_inputsource, # alternatively, use a customized InputSource
-   -           callbacks=[...]
-   -         )
-   -
-   -# start training:
-   -SomeTrainer(config, other_arguments).train()
-   -
-   -# start multi-GPU training with synchronous update:
-   -# SyncMultiGPUTrainerParameterServer(config).train()
-   -```
-   -
-   -When you set the DataFlow (rather than the InputSource) in the config,
-   -tensorpack trainers automatically adopt certain prefetch mechanism, as mentioned
-   -in the [Input Pipeline](input-source.html) tutorial.
-   -You can set the InputSource instead, to customize this behavior.
-	 -->
-Trainers are being redesigned, this page will be updated soon.
+Most neural network training tasks are single-cost optimization.
+Tensorpack provides some trainer implementations for such tasks.
+These trainers will build the graph based on inputs and functions which build the cost from inputs.
+
+The simplest way to use trainers, is to pass a
+`TrainConfig` to the `launch_train_with_config` high-level wrapper.
+
+```python
+config = TrainConfig(
+	 model=MyModel()
+	 dataflow=my_dataflow,
+	 # data=my_inputsource, # alternatively, use a customized InputSource
+	 callbacks=[...]
+)
+
+trainer = SomeTrainer()
+# multi-GPU training with synchronous update:
+# trainer = SyncMultiGPUTrainerParameterServer([0, 1, 2])
+launch_train_with_config(config, trainer)
+```
+
+When you set the DataFlow (rather than the InputSource) in the config,
+`launch_train_with_config` automatically adopt certain prefetch mechanism, as mentioned
+in the [Input Pipeline](input-source.html) tutorial.
+You can set the InputSource instead, to customize this behavior.
 
 Existing multi-GPU trainers include the logic of data-parallel training.
 You can enable them by just one line, and all the necessary logic to achieve the best performance was baked into the trainers already.

examples/GAN/GAN.py

@@ -7,7 +7,7 @@ import tensorflow as tf
 import numpy as np
 import time
 from tensorpack import (Trainer, QueueInput,
-                        ModelDescBase, DataFlow, StagingInputWrapper,
+                        ModelDescBase, DataFlow, StagingInput,
                         TowerContext)
 from tensorpack.graph_builder import DataParallelBuilder, LeastLoadedDeviceSetter
 from tensorpack.tfutils.summary import add_moving_summary
@@ -136,7 +136,7 @@ class MultiGPUGANTrainer(Trainer):
         raw_devices = ['/gpu:{}'.format(k) for k in config.tower]
 
         # setup input
-        input = StagingInputWrapper(QueueInput(config.dataflow), config.tower)
+        input = StagingInput(QueueInput(config.dataflow), config.tower)
         model = config.model
         cbs = input.setup(model.get_inputs_desc())
         config.callbacks.extend(cbs)

tensorpack/callbacks/inference_runner.py

@@ -203,7 +203,7 @@ class DataParallelInferenceRunner(InferenceRunnerBase):
         self._input_callbacks = Callbacks(input_callbacks)
 
         # InputSource might have hooks which break us.
-        # e.g. hooks from StagingInputWrapper will force the consumption
+        # e.g. hooks from StagingInput will force the consumption
         # of nr_tower datapoints in every run.
         input_hooks = self._input_callbacks.get_hooks()
         self._hooks = [self._build_hook(inf) for inf in self.infs] + input_hooks

tensorpack/input_source/input_source.py

@@ -28,7 +28,8 @@ __all__ = ['PlaceholderInput', 'FeedInput',
            'QueueInput', 'BatchQueueInput',
            'DummyConstantInput', 'TensorInput',
            'TFDatasetInput',
-           'StagingInputWrapper']
+           'StagingInputWrapper',
+           'StagingInput']
 
 
 class PlaceholderInput(InputSource):
@@ -398,7 +399,7 @@ class TFDatasetInput(FeedfreeInput):
         return self._iterator.get_next()
 
 
-class StagingInputWrapper(FeedfreeInput):
+class StagingInput(FeedfreeInput):
     """
     A wrapper around a feedfree input,
     to prefetch the input in StagingArea (on GPUs).
@@ -433,7 +434,7 @@ class StagingInputWrapper(FeedfreeInput):
         self._input = input
         if not isinstance(towers[0], int):
             # API changed
-            log_deprecated("StagingInputWrapper(devices=)", "Use (towers=) instead!", "2018-01-31")
+            log_deprecated("StagingInput(devices=)", "Use (towers=) instead!", "2018-01-31")
             self._devices = towers
         else:
             self._devices = ['/gpu:{}'.format(k) for k in towers]
@@ -451,7 +452,7 @@ class StagingInputWrapper(FeedfreeInput):
         cbs = self._input.get_callbacks()
 
         cbs.append(
-            StagingInputWrapper.StagingCallback(
+            StagingInput.StagingCallback(
                 self._get_stage_op(), self._get_unstage_op(), self._nr_stage))
         return cbs
 
@@ -488,3 +489,6 @@ class StagingInputWrapper(FeedfreeInput):
         with self.cached_name_scope():
             all_outputs = list(chain.from_iterable(self._unstage_ops))
             return tf.group(*all_outputs)
+
+
+StagingInputWrapper = StagingInput

tensorpack/train/interface.py

@@ -5,7 +5,7 @@
 import tensorflow as tf
 
 from ..input_source import (
-    InputSource, FeedInput, QueueInput, StagingInputWrapper, DummyConstantInput)
+    InputSource, FeedInput, QueueInput, StagingInput, DummyConstantInput)
 
 from ..trainv1.config import TrainConfig
 from .base import SingleCostTrainer
@@ -36,8 +36,8 @@ def apply_default_prefetch(input_source_or_dataflow, trainer, towers):
         assert not isinstance(trainer, SimpleTrainer)
         assert tf.test.is_gpu_available()
 
-        if not isinstance(input, (StagingInputWrapper, DummyConstantInput)):
-            input = StagingInputWrapper(input, towers)
+        if not isinstance(input, (StagingInput, DummyConstantInput)):
+            input = StagingInput(input, towers)
     return input
 
 

tensorpack/trainv1/config.py

@@ -19,7 +19,7 @@ __all__ = ['TrainConfig']
 
 class TrainConfig(object):
     """
-    Config for trainer.
+    A collection of options to be used for trainers.
     """
 
     def __init__(self,

tensorpack/trainv1/multigpu.py

@@ -8,7 +8,7 @@ import tensorflow as tf
 from ..callbacks.graph import RunOp
 from ..utils.develop import log_deprecated
 
-from ..input_source import QueueInput, StagingInputWrapper, DummyConstantInput
+from ..input_source import QueueInput, StagingInput, DummyConstantInput
 from ..graph_builder.training import (
     SyncMultiGPUParameterServerBuilder,
     SyncMultiGPUReplicatedBuilder,
@@ -43,8 +43,8 @@ def apply_prefetch_policy(config, gpu_prefetch=True):
         assert tf.test.is_gpu_available()
 
         # seem to only improve on >1 GPUs
-        if not isinstance(config.data, (StagingInputWrapper, DummyConstantInput)):
-            config.data = StagingInputWrapper(config.data, config.tower)
+        if not isinstance(config.data, (StagingInput, DummyConstantInput)):
+            config.data = StagingInput(config.data, config.tower)
 
 
 class SyncMultiGPUTrainerParameterServer(Trainer):