From f7400856789ad516b1c79ea92bbadb09367cf5b7 Mon Sep 17 00:00:00 2001 From: Kaushik B <45285388+kaushikb11@users.noreply.github.com> Date: Thu, 24 Mar 2022 11:57:10 +0530 Subject: [PATCH] Add Progress Bar to docs (#11359) Co-authored-by: Ethan Harris Co-authored-by: thomas chaton Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> --- docs/source/common/progress_bar.rst | 138 ++++++++++++++++++++++++++++ docs/source/extensions/logging.rst | 2 + docs/source/index.rst | 1 + 3 files changed, 141 insertions(+) create mode 100644 docs/source/common/progress_bar.rst diff --git a/docs/source/common/progress_bar.rst b/docs/source/common/progress_bar.rst new file mode 100644 index 0000000000..92663ef752 --- /dev/null +++ b/docs/source/common/progress_bar.rst @@ -0,0 +1,138 @@ +.. testsetup:: * + + from pytorch_lightning.trainer.trainer import Trainer + +.. _progress_bar: + + +Progress Bar +============ + +Lightning supports two different types of progress bars (`tqdm `_ and `rich `_). :class:`~pytorch_lightning.callbacks.TQDMProgressBar` is used by default, +but you can override it by passing a custom :class:`~pytorch_lightning.callbacks.TQDMProgressBar` or :class:`~pytorch_lightning.callbacks.RichProgressBar` to the ``callbacks`` argument of the :class:`~pytorch_lightning.trainer.trainer.Trainer`. + +You could also use the :class:`~pytorch_lightning.callbacks.ProgressBarBase` class to implement your own progress bar. + +------------- + +TQDMProgressBar +--------------- + +The :class:`~pytorch_lightning.callbacks.TQDMProgressBar` uses the `tqdm `_ library internally and is the default progress bar used by Lightning. +It prints to ``stdout`` and shows up to four different bars: + +- **sanity check progress:** the progress during the sanity check run +- **main progress:** shows training + validation progress combined. It also accounts for multiple validation runs during training when :paramref:`~pytorch_lightning.trainer.trainer.Trainer.val_check_interval` is used. +- **validation progress:** only visible during validation; shows total progress over all validation datasets. +- **test progress:** only active when testing; shows total progress over all test datasets. + +For infinite datasets, the progress bar never ends. + +You can update ``refresh_rate`` (rate (number of batches) at which the progress bar get updated) for :class:`~pytorch_lightning.callbacks.TQDMProgressBar` by: + +.. code-block:: python + + from pytorch_lightning.callbacks import TQDMProgressBar + + trainer = Trainer(callbacks=[TQDMProgressBar(refresh_rate=10)]) + +If you want to customize the default :class:`~pytorch_lightning.callbacks.TQDMProgressBar` used by Lightning, you can override +specific methods of the callback class and pass your custom implementation to the :class:`~pytorch_lightning.trainer.trainer.Trainer`. + +.. code-block:: python + + class LitProgressBar(TQDMProgressBar): + def init_validation_tqdm(self): + bar = super().init_validation_tqdm() + bar.set_description("running validation...") + return bar + + + trainer = Trainer(callbacks=[LitProgressBar()]) + +.. seealso:: + - :class:`~pytorch_lightning.callbacks.TQDMProgressBar` docs. + - `tqdm library `__ + +---------------- + +RichProgressBar +--------------- + +`Rich `_ is a Python library for rich text and beautiful formatting in the terminal. +To use the :class:`~pytorch_lightning.callbacks.RichProgressBar` as your progress bar, first install the package: + +.. code-block:: bash + + pip install rich + +Then configure the callback and pass it to the :class:`~pytorch_lightning.trainer.trainer.Trainer`: + +.. code-block:: python + + from pytorch_lightning.callbacks import RichProgressBar + + trainer = Trainer(callbacks=[RichProgressBar()]) + +Customize the theme for your :class:`~pytorch_lightning.callbacks.RichProgressBar` like this: + +.. code-block:: python + + from pytorch_lightning.callbacks import RichProgressBar + from pytorch_lightning.callbacks.progress.rich_progress import RichProgressBarTheme + + # create your own theme! + progress_bar = RichProgressBar( + theme=RichProgressBarTheme( + description="green_yellow", + progress_bar="green1", + progress_bar_finished="green1", + progress_bar_pulse="#6206E0", + batch_progress="green_yellow", + time="grey82", + processing_speed="grey82", + metrics="grey82", + ) + ) + + trainer = Trainer(callbacks=progress_bar) + +You can customize the components used within :class:`~pytorch_lightning.callbacks.RichProgressBar` with ease by overriding the +:func:`~pytorch_lightning.callbacks.RichProgressBar.configure_columns` method. + +.. code-block:: python + + from rich.progress import TextColumn + + custom_column = TextColumn("[progress.description]Custom Rich Progress Bar!") + + + class CustomRichProgressBar(RichProgressBar): + def configure_columns(self, trainer): + return [custom_column] + + + progress_bar = CustomRichProgressBar() + +If you wish for a new progress bar to be displayed at the end of every epoch, you should enable +:paramref:`RichProgressBar.leave ` by passing ``True`` + +.. code-block:: python + + from pytorch_lightning.callbacks import RichProgressBar + + trainer = Trainer(callbacks=[RichProgressBar(leave=True)]) + +.. seealso:: + - :class:`~pytorch_lightning.callbacks.RichProgressBar` docs. + - :class:`~pytorch_lightning.callbacks.RichModelSummary` docs to customize the model summary table. + - `Rich library `__. + + +.. note:: + + Progress bar is automatically enabled with the Trainer, and to disable it, one should do this: + + .. code-block:: python + + trainer = Trainer(enable_progress_bar=False) diff --git a/docs/source/extensions/logging.rst b/docs/source/extensions/logging.rst index ccbfe0fb06..08e7d47810 100644 --- a/docs/source/extensions/logging.rst +++ b/docs/source/extensions/logging.rst @@ -287,6 +287,8 @@ method, setting ``prog_bar=True``. self.log("my_loss", loss, prog_bar=True) +You could learn more about progress bars supported by Lightning :doc:`here <../common/progress_bar>`. + Modifying the Progress Bar ========================== diff --git a/docs/source/index.rst b/docs/source/index.rst index b3e080fbcc..4e7543b51f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -112,6 +112,7 @@ Welcome to PyTorch Lightning common/remote_fs advanced/training_tricks advanced/pruning_quantization + common/progress_bar advanced/transfer_learning common/evaluation