introduce on_before_optimizer_setup hook

Author: deependujha

src/lightning/pytorch/callbacks/callback.py

@@ -277,6 +277,14 @@ def on_before_backward(self, trainer: "pl.Trainer", pl_module: "pl.LightningModu
     def on_after_backward(self, trainer: "pl.Trainer", pl_module: "pl.LightningModule") -> None:
         """Called after ``loss.backward()`` and before optimizers are stepped."""
 
+    def on_before_optimizer_setup(self, trainer: "pl.Trainer", pl_module: "pl.LightningModule") -> None:
+        """Called after :meth:`~lightning.pytorch.core.hooks.ModelHooks.configure_model` but before
+        :meth:`~lightning.pytorch.core.hooks.ModelHooks.configure_optimizers`.
+
+        Useful when you need to make changes to the model before the optimizers are set up (e.g. freezing layers).
+
+        """
+
     def on_before_optimizer_step(
         self, trainer: "pl.Trainer", pl_module: "pl.LightningModule", optimizer: Optimizer
     ) -> None:

src/lightning/pytorch/callbacks/finetuning.py

@@ -105,8 +105,8 @@ def load_state_dict(self, state_dict: dict[str, Any]) -> None:
             self._internal_optimizer_metadata = state_dict  # type: ignore[assignment]
 
     @override
-    def on_fit_start(self, trainer: "pl.Trainer", pl_module: "pl.LightningModule") -> None:
-        # freeze the required modules before training
+    def on_before_optimizer_setup(self, trainer: "pl.Trainer", pl_module: "pl.LightningModule") -> None:
+        # freeze the required modules before optimizers are created & after `configure_model` is run
         self.freeze_before_training(pl_module)
 
         from lightning.pytorch.strategies import DeepSpeedStrategy
@@ -117,6 +117,8 @@ def on_fit_start(self, trainer: "pl.Trainer", pl_module: "pl.LightningModule") -
                 " Choose a different strategy or disable the callback."
             )
 
+    @override
+    def on_fit_start(self, trainer: "pl.Trainer", pl_module: "pl.LightningModule") -> None:
         # restore the param_groups created during the previous training.
         if self._restarting:
             named_parameters = dict(pl_module.named_parameters())

src/lightning/pytorch/callbacks/lambda_function.py

@@ -69,6 +69,7 @@ def __init__(
         on_load_checkpoint: Optional[Callable] = None,
         on_before_backward: Optional[Callable] = None,
         on_after_backward: Optional[Callable] = None,
+        on_before_optimizer_setup: Optional[Callable] = None,
         on_before_optimizer_step: Optional[Callable] = None,
         on_before_zero_grad: Optional[Callable] = None,
         on_predict_start: Optional[Callable] = None,

src/lightning/pytorch/core/hooks.py

@@ -295,6 +295,29 @@ def on_after_backward(self) -> None:
 
         """
 
+    def on_before_optimizer_setup(self) -> None:
+        """Called after :meth:`~lightning.pytorch.core.hooks.ModelHooks.configure_model` but before
+        :meth:`~lightning.pytorch.core.hooks.ModelHooks.configure_optimizers`.
+
+        This hook provides a safe point to modify, freeze, or inspect model parameters before optimizers are created.
+        It’s particularly useful for callbacks such as
+        :class:`~lightning.pytorch.callbacks.finetuning.BaseFinetuning`, where parameters must be frozen
+        prior to optimizer setup.
+
+        This hook runs once in fit stage, after the model
+        has been fully instantiated by ``configure_model``.
+
+        Example::
+
+            class MyFinetuneCallback(Callback):
+                def on_before_optimizer_setup(self, trainer, pl_module):
+                    # freeze the backbone before optimizers are created
+                    for param in pl_module.backbone.parameters():
+                        param.requires_grad = False
+
+        """
+        pass
+
     def on_before_optimizer_step(self, optimizer: Optimizer) -> None:
         """Called before ``optimizer.step()``.
 

src/lightning/pytorch/trainer/trainer.py

@@ -989,6 +989,11 @@ def _run(
         log.debug(f"{self.__class__.__name__}: configuring model")
         call._call_configure_model(self)
 
+        # run hook `on_before_optimizer_setup` before optimizers are set up & after model is configured
+        if self.state.fn == TrainerFn.FITTING:
+            call._call_callback_hooks(self, "on_before_optimizer_setup")
+            call._call_lightning_module_hook(self, "on_before_optimizer_setup")
+
         # check if we should delay restoring checkpoint till later
         if not self.strategy.restore_checkpoint_after_setup:
             log.debug(f"{self.__class__.__name__}: restoring module and callbacks from checkpoint path: {ckpt_path}")