Merge branch 'master' into usort

Author: vfdev-5

Diff for: docs/source/metrics.rst

@@ -4,8 +4,17 @@ ignite.metrics
 Metrics provide a way to compute various quantities of interest in an online
 fashion without having to store the entire output history of a model.
 
-In practice a user needs to attach the metric instance to an engine. The metric
-value is then computed using the output of the engine's ``process_function``:
+Attach Engine API
+------------------
+
+The metrics as stated above are computed in a online fashion, which means that the metric instance accumulates some internal counters on 
+each iteration and metric value is computed once the epoch is ended. Internal counters are reset after every epoch. In practice, this is done with the 
+help of three methods: :meth:`~ignite.metrics.metric.Metric.reset()`, :meth:`~ignite.metrics.metric.Metric.update()` and :meth:`~ignite.metrics.metric.Metric.compute()`.
+
+Therefore, a user needs to attach the metric instance to the engine so that the above three methods can be triggered on execution of certain :class:`~ignite.engine.events.Events`.
+The :meth:`~ignite.metrics.metric.Metric.reset()` method is triggered on ``EPOCH_STARTED`` event and it is responsible to reset the metric to its initial state. The :meth:`~ignite.metrics.metric.Metric.update()` method is triggered
+on ``ITERATION_COMPLETED`` event as it updates the state of the metric using the passed batch output. And :meth:`~ignite.metrics.metric.Metric.compute()` is triggered on ``EPOCH_COMPLETED``
+event. It computes the metric based on its accumulated states. The metric value is computed using the output of the engine's ``process_function``:
 
 .. code-block:: python
 

Diff for: ignite/handlers/param_scheduler.py

@@ -804,22 +804,22 @@ class LRScheduler(ParamScheduler):
 
             default_trainer = get_default_trainer()
 
-            @default_trainer.on(Events.ITERATION_STARTED)
-            def print_lr():
-                print(default_optimizer.param_groups[0]["lr"])
-
             from torch.optim.lr_scheduler import StepLR
 
             torch_lr_scheduler = StepLR(default_optimizer, step_size=3, gamma=0.1)
 
             scheduler = LRScheduler(torch_lr_scheduler)
 
+            @default_trainer.on(Events.ITERATION_COMPLETED)
+            def print_lr():
+                print(default_optimizer.param_groups[0]["lr"])
+
             # In this example, we assume to have installed PyTorch>=1.1.0
             # (with new `torch.optim.lr_scheduler` behaviour) and
             # we attach scheduler to Events.ITERATION_COMPLETED
             # instead of Events.ITERATION_STARTED to make sure to use
             # the first lr value from the optimizer, otherwise it is will be skipped:
-            default_trainer.add_event_handler(Events.ITERATION_STARTED, scheduler)
+            default_trainer.add_event_handler(Events.ITERATION_COMPLETED, scheduler)
 
             default_trainer.run([0] * 8, max_epochs=1)