class_docstr: Tuner class to tune your model.
docstr: Iteratively try to find the largest batch size for a given model that does not give an out of memory (OOM)
  error.
  
  Args:
      model: Model to tune.
      train_dataloaders: A collection of :class:`torch.utils.data.DataLoader` or a
          :class:`~lightning.pytorch.core.datamodule.LightningDataModule` specifying training samples.
          In the case of multiple dataloaders, please see this :ref:`section <multiple-dataloaders>`.
      val_dataloaders: A :class:`torch.utils.data.DataLoader` or a sequence of them specifying validation samples.
      dataloaders: A :class:`torch.utils.data.DataLoader` or a sequence of them specifying val/test/predict
          samples used for running tuner on validation/testing/prediction.
      datamodule: An instance of :class:`~lightning.pytorch.core.datamodule.LightningDataModule`.
      method: Method to run tuner on. It can be any of ``("fit", "validate", "test", "predict")``.
      mode: Search strategy to update the batch size:
  
          - ``'power'``: Keep multiplying the batch size by 2, until we get an OOM error.
          - ``'binsearch'``: Initially keep multiplying by 2 and after encountering an OOM error
              do a binary search between the last successful batch size and the batch size that failed.
  
      steps_per_trial: number of steps to run with a given batch size.
          Ideally 1 should be enough to test if an OOM error occurs,
          however in practise a few are needed
      init_val: initial batch size to start the search with
      max_trials: max number of increases in batch size done before
         algorithm is terminated
      batch_arg_name: name of the attribute that stores the batch size.
          It is expected that the user has provided a model or datamodule that has a hyperparameter
          with that name. We will look for this attribute name in the following places
  
          - ``model``
          - ``model.hparams``
          - ``trainer.datamodule`` (the datamodule passed to the tune method)
code: def scale_batch_size(
      self,
      model: "pl.LightningModule",
      train_dataloaders: Optional[
          Union[TRAIN_DATALOADERS, "pl.LightningDataModule"]
      ] = None,
      val_dataloaders: Optional[EVAL_DATALOADERS] = None,
      dataloaders: Optional[EVAL_DATALOADERS] = None,
      datamodule: Optional["pl.LightningDataModule"] = None,
      method: Literal["fit", "validate", "test", "predict"] = "fit",
      mode: str = "power",
      steps_per_trial: int = 3,
      init_val: int = 2,
      max_trials: int = 25,
      batch_arg_name: str = "batch_size",
  ) -> Optional[int]:
      """Iteratively try to find the largest batch size for a given model that does not give an out of memory (OOM)
      error.
  
      Args:
          model: Model to tune.
          train_dataloaders: A collection of :class:`torch.utils.data.DataLoader` or a
              :class:`~lightning.pytorch.core.datamodule.LightningDataModule` specifying training samples.
              In the case of multiple dataloaders, please see this :ref:`section <multiple-dataloaders>`.
          val_dataloaders: A :class:`torch.utils.data.DataLoader` or a sequence of them specifying validation samples.
          dataloaders: A :class:`torch.utils.data.DataLoader` or a sequence of them specifying val/test/predict
              samples used for running tuner on validation/testing/prediction.
          datamodule: An instance of :class:`~lightning.pytorch.core.datamodule.LightningDataModule`.
          method: Method to run tuner on. It can be any of ``("fit", "validate", "test", "predict")``.
          mode: Search strategy to update the batch size:
  
              - ``'power'``: Keep multiplying the batch size by 2, until we get an OOM error.
              - ``'binsearch'``: Initially keep multiplying by 2 and after encountering an OOM error
                  do a binary search between the last successful batch size and the batch size that failed.
  
          steps_per_trial: number of steps to run with a given batch size.
              Ideally 1 should be enough to test if an OOM error occurs,
              however in practise a few are needed
          init_val: initial batch size to start the search with
          max_trials: max number of increases in batch size done before
             algorithm is terminated
          batch_arg_name: name of the attribute that stores the batch size.
              It is expected that the user has provided a model or datamodule that has a hyperparameter
              with that name. We will look for this attribute name in the following places
  
              - ``model``
              - ``model.hparams``
              - ``trainer.datamodule`` (the datamodule passed to the tune method)
  
      """
      _check_tuner_configuration(
          train_dataloaders, val_dataloaders, dataloaders, method
      )
      _check_scale_batch_size_configuration(self._trainer)
  
      # local import to avoid circular import
      from lightning.pytorch.callbacks.batch_size_finder import (
          BatchSizeFinder,
      )
  
      batch_size_finder: Callback = BatchSizeFinder(
          mode=mode,
          steps_per_trial=steps_per_trial,
          init_val=init_val,
          max_trials=max_trials,
          batch_arg_name=batch_arg_name,
      )
      # do not continue with the loop in case Tuner is used
      batch_size_finder._early_exit = True
      self._trainer.callbacks = [
          batch_size_finder
      ] + self._trainer.callbacks
  
      if method == "fit":
          self._trainer.fit(
              model, train_dataloaders, val_dataloaders, datamodule
          )
      elif method == "validate":
          self._trainer.validate(
              model, dataloaders, datamodule=datamodule
          )
      elif method == "test":
          self._trainer.test(model, dataloaders, datamodule=datamodule)
      elif method == "predict":
          self._trainer.predict(
              model, dataloaders, datamodule=datamodule
          )
  
      self._trainer.callbacks = [
          cb
          for cb in self._trainer.callbacks
          if cb is not batch_size_finder
      ]
      return batch_size_finder.optimal_batch_size
  
file_path: pytorch-lightning/src/lightning/pytorch/tuner/tuning.py
imports: from typing import TYPE_CHECKING, Literal, Optional, Union
  import lightning.pytorch
  from lightning.pytorch.callbacks.callback import Callback
  from lightning.pytorch.utilities.exceptions import MisconfigurationException
  from lightning.pytorch.utilities.types import EVAL_DATALOADERS, TRAIN_DATALOADERS
label_desc: Use image node_id 2 for calling the Tuner obj's underlying member method code with example usage: obj.scale_batch_size(model, train_dataloaders, val_dataloaders, dataloaders, datamodule, method, mode, steps_per_trial, init_val, max_trials, batch_arg_name) and returns: batch_size_finder