From 711892a0a293f7c7f951eba0907e1c0ccd2b37d8 Mon Sep 17 00:00:00 2001
From: authman <uapatira@gmail.com>
Date: Thu, 19 Mar 2020 08:22:29 -0500
Subject: [PATCH] Fix Configuring Learning Rate Schedulers (#1177)

* Update docs so users know the desired manner of configuring learning rate schedulers.

* update list

* as note

Co-authored-by: Jirka Borovec <Borda@users.noreply.github.com>
---
 docs/source/optimizers.rst          | 14 ++++++++++++
 pytorch_lightning/core/lightning.py | 33 ++++++++++++++---------------
 2 files changed, 30 insertions(+), 17 deletions(-)

diff --git a/docs/source/optimizers.rst b/docs/source/optimizers.rst
index 1d9e77a7de..9020d50091 100644
--- a/docs/source/optimizers.rst
+++ b/docs/source/optimizers.rst
@@ -19,6 +19,20 @@ Every optimizer you use can be paired with any `LearningRateScheduler <https://p
    def configure_optimizers(self):
       return [Adam(...), SGD(...)], [ReduceLROnPlateau(), LambdaLR()]
 
+   # Same as above with additional params passed to the first scheduler
+   def configure_optimizers(self):
+      optimizers = [Adam(...), SGD(...)]
+      schedulers = [
+         {
+            'scheduler': ReduceLROnPlateau(mode='max', patience=7),
+            'monitor': 'val_recall', # Default: val_loss
+            'interval': 'epoch',
+            'frequency': 1
+         },
+         LambdaLR()
+      ]
+      return optimizers, schedulers
+
 
 Use multiple optimizers (like GANs)
 -------------------------------------
diff --git a/pytorch_lightning/core/lightning.py b/pytorch_lightning/core/lightning.py
index d5b408423d..01c229285b 100644
--- a/pytorch_lightning/core/lightning.py
+++ b/pytorch_lightning/core/lightning.py
@@ -942,28 +942,27 @@ class LightningModule(ABC, GradInformation, ModelIO, ModelHooks):
                     dis_sched = CosineAnnealing(discriminator_opt, T_max=10) # called every epoch
                     return [gen_opt, dis_opt], [gen_sched, dis_sched]
 
-        Some things to know
-
+        .. note:: Some things to note:
             - Lightning calls ``.backward()`` and ``.step()`` on each optimizer
-            and learning rate scheduler as needed.
-
+             and learning rate scheduler as needed.
             - If you use 16-bit precision (``precision=16``), Lightning will automatically
-            handle the optimizers for you.
-
-            - If you use multiple optimizers, training_step will have an additional
-            ``optimizer_idx`` parameter.
-
-            - If you use LBFGS lightning handles the closure function automatically for you
-
+             handle the optimizers for you.
+            - If you use multiple optimizers, training_step will have an additional ``optimizer_idx`` parameter.
+            - If you use LBFGS lightning handles the closure function automatically for you.
             - If you use multiple optimizers, gradients will be calculated only
-            for the parameters of current optimizer at each training step.
-
+             for the parameters of current optimizer at each training step.
             - If you need to control how often those optimizers step or override the
-            default .step() schedule, override the `optimizer_step` hook.
-
+             default .step() schedule, override the `optimizer_step` hook.
             - If you only want to call a learning rate scheduler every `x` step or epoch,
-            you can input this as 'frequency' key: dict(scheduler=lr_scheduler,
-                                                        interval='step' or 'epoch', frequency=x)
+             or want to monitor a custom metric, you can specify these in a dictionary:
+                .. code-block:: python
+
+                    {
+                        'scheduler': lr_scheduler,
+                        'interval': 'step'  # or 'epoch'
+                        'monitor': 'val_f1',
+                        'frequency': x
+                    }
 
         """
         return Adam(self.parameters(), lr=1e-3)