loop customization docs #9609

awaelchli · 2021-09-20T14:04:43Z

What does this PR do?

Continuation of #9557 with new structure.

TODO:

move the final GIFs to the S3 bucket and include via link

Before submitting

Was this discussed/approved via a GitHub issue? (not for typos and docs)
Did you read the contributor guideline, Pull Request section?
Did you make sure your PR does only one thing, instead of bundling different changes together?
Did you make sure to update the documentation with your changes? (if necessary)
Did you write any new necessary tests? (not for typos and docs)
Did you verify new and existing tests pass locally with your changes?
Did you update the CHANGELOG? (not for typos, docs, test updates, or internal minor changes/refactorings)

PR review

Anyone in the community is free to review the PR once the tests have passed.
Before you start reviewing make sure you have read Review guidelines. In short, see the following bullet-list:

Is this pull request ready for review? (if not, please submit in draft mode)
Check that all items from Before submitting are resolved
Make sure the title is self-explanatory and the description concisely explains the PR
Add labels and milestones (and optionally projects) to the PR so it can be classified

Did you have fun?

I made sure I had fun coding 🙃

for more information, see https://pre-commit.ci

Co-authored-by: Carlos Mocholí <[email protected]>

Co-authored-by: thomas chaton <[email protected]>

for more information, see https://pre-commit.ci

docs/source/advanced/loops.rst

lantiga

Big improvement compared to the previous iteration, we can still improve, up to us when to do it. I have left comments inline.

A comment on the graphics: I really like the gifs, but I noticed that except for the first gif, the last frame only persists on screen for a fraction of a second, while it should stay there for a full few seconds. It's really hard to consume it right now.

docs/source/extensions/loops.rst

docs/source/extensions/loops_advanced.rst

lantiga · 2021-10-11T22:50:49Z

docs/source/extensions/loops_advanced.rst

+        # train generator, then yield
+        fake_pred = self.discriminator(fake)
+        gen_loss = self.criterion(fake_pred, fake_gt)
+        yield gen_loss


This example is not easy to follow, I had to go back and forth a few times to grasp it. We should probably make an effort at making it more digestible by avoiding glossing over details, and explaining (in words or visually) how the generator will be advanced once per optimizer.

Thanks Luca, I agree it's quite complex. The use case is simple but the implementation at the moment is not so easy. As we will continue to improve access to loop customization, this should become much cleaner. For now, I'm taking the example out of the docs and will create a tutorial example instead here: #9983

Plus, we will add more api docs to the loops, especially for the undocumented methods, so they become accessible through our doc pages.

codecov · 2021-10-15T16:16:23Z

Codecov Report

Merging #9609 (7bfacdb) into master (23450e2) will decrease coverage by 0%.
The diff coverage is 100%.

@@           Coverage Diff           @@
##           master   #9609    +/-   ##
=======================================
- Coverage      93%     93%    -0%     
=======================================
  Files         180     179     -1     
  Lines       15090   15829   +739     
=======================================
+ Hits        14019   14670   +651     
- Misses       1071    1159    +88

edenlightning

Looks great!

Just a note, better to replace all references to classes and functions with cross references (:class:~pytorch_lightning.core.optimizer.LightningOptimizer etc)

docs/source/extensions/loops.rst

kaushikb11

LGTM!

…docs/loop-customization

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Carlos Mocholí <[email protected]> Co-authored-by: thomas chaton <[email protected]> Co-authored-by: edenlightning <[email protected]>

Borda · 2021-10-19T23:05:17Z

docs/source/extensions/loops.rst

+        val_loss = 0
+        for i, val_batch in enumerate(val_dataloader):
+            x, y = val_batch
+            y_hat = model(x)
+            val_loss += loss_function(y_hat, y)


looks a bit strange running full validation loop for each training step/batch

we want to enable strange things with loop customization :)) we wouldn't be able to do this so cleanly in pure Lightning. That's the core value haha

Borda · 2021-10-19T23:07:01Z

docs/source/extensions/loops.rst

+        optimizer.step()
+
+However, some new research use cases such as meta-learning, active learning, recommendation systems, etc., require a different loop structure.
+For example here is a simple loop that guides the weight updates with a loss from a special validation split:


can we refer to some literature? this kind of weight update is not very common...

the closest I could think of is bilevel learning: https://arxiv.org/pdf/1809.01465.pdf
What I sketched here in the docs is not exactly that but I couldn't add too many details because the focus should be on the illustration of the loop structure, less on the details of how such an approach would be useful in practice.

docs/source/extensions/loops.rst

Borda · 2021-10-19T23:08:35Z

docs/source/extensions/loops.rst

+Each loop has a series of methods that can be modified.
+For example with the :class:`~pytorch_lightning.loops.fit_loop.FitLoop`:
+
+.. code-block::


.. code-block:: python

pre-commit/blacken-docs was not happy. couldn't figure out the problem

but others seem to have it...

yes, in other sections blacken-docs does not fail with a cryptic error :(
If you find the fix I will buy you a beer/coffee

Am I eligible for the free beer?

It fails because your forgot the ":" in the on_advance_end def

Also, the advance def should take self for consistency (but this does not make it fail).

🍺🍺🍺

Ah, thank you very much!
#10036

Send me your home address on slack, I'll ship the beer asap 😃

Borda · 2021-10-19T23:09:59Z

docs/source/extensions/loops.rst

+
+.. _override default loops:
+
+Overriding the default loops


just thinking is all loops kind if tested with in the Traner sanity check?

nope, only the validation loop :)

awaelchli and others added 27 commits September 15, 2021 15:05

add introduction draft

f6fe9ee

trainer entry point section

3836641

add api reference

15d74ff

base class section draft

40bcfb6

faq drat and notes

762f4e9

default loop description

d439db7

loop customization section

97ad8d7

remove notes

e2626ae

rename file

fd30f8b

add loop page to index

4cf9d04

fix typo

fad1106

persisting state

2e887cb

fix typo in code-block

ff784a7

add FAQ

4710ce9

fix underline

16f46fc

fix todo's for links

6ff22c5

update Q/A format

c140209

blacken docs

d56f20e

make comments fit on the page

c0edf98

[pre-commit.ci] auto fixes from pre-commit.com hooks

79967b3

for more information, see https://pre-commit.ci

backticks and typos

773f1b6

Co-authored-by: Carlos Mocholí <[email protected]>

add missing backticks

6919352

remove "-"

f6c83af

several rewordings and typos

9c9bd78

Co-authored-by: thomas chaton <[email protected]>

[pre-commit.ci] auto fixes from pre-commit.com hooks

4add03c

for more information, see https://pre-commit.ci

rewrite intro

c9bfe7e

rename files

dda835a

awaelchli force-pushed the docs/loop-customization-2 branch from ca89b80 to dda835a Compare September 20, 2021 14:07

[pre-commit.ci] auto fixes from pre-commit.com hooks

cc9fd1b

for more information, see https://pre-commit.ci

awaelchli commented Sep 20, 2021

View reviewed changes

docs/source/advanced/loops.rst Outdated Show resolved Hide resolved

lantiga reviewed Oct 11, 2021

View reviewed changes

awaelchli added 3 commits October 14, 2021 13:19

add section in new_project.rst

bca424f

restructure and rewrite based on william falcon feedback (wip)

fea848c

update section header

c9adcc3

tchaton marked this pull request as ready for review October 15, 2021 15:52

tchaton requested review from Borda, carmocca and justusschock as code owners October 15, 2021 15:52

edenlightning approved these changes Oct 15, 2021

View reviewed changes

mergify bot added the ready PRs ready to be merged label Oct 15, 2021

kaushikb11 reviewed Oct 16, 2021

View reviewed changes

docs/source/extensions/loops.rst Outdated Show resolved Hide resolved

update on comments

87a9838

kaushikb11 approved these changes Oct 16, 2021

View reviewed changes

awaelchli added 7 commits October 16, 2021 20:51

Merge remote-tracking branch 'origin/docs/loop-customization-2' into …

e307d02

…docs/loop-customization

updates

a456b9a

replace files with link to s3

cea2981

ignore blacken docs error

ae6bc23

update references

9ab2bb4

update api references

6ac59a7

punctuation

a119ddc

awaelchli mentioned this pull request Oct 18, 2021

Add Yield loop example #9983

Merged

12 tasks

remove yield example

7bfacdb

awaelchli enabled auto-merge (squash) October 18, 2021 09:10

awaelchli merged commit 7a91516 into master Oct 18, 2021

awaelchli deleted the docs/loop-customization-2 branch October 18, 2021 09:43

awaelchli mentioned this pull request Oct 18, 2021

Update docs for base Loop class with examples #9993

Merged

11 tasks

Borda reviewed Oct 19, 2021

View reviewed changes

awaelchli mentioned this pull request Oct 20, 2021

Update syntax errors in docs code snippets #10036

Merged

11 tasks

loop customization docs #9609

loop customization docs #9609

Uh oh!

Conversation

awaelchli commented Sep 20, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Before submitting

PR review

Did you have fun?

Uh oh!

Uh oh!

lantiga left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Oct 15, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

edenlightning left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kaushikb11 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

awaelchli Oct 19, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

awaelchli commented Sep 20, 2021 •

edited

Loading

codecov bot commented Oct 15, 2021 •

edited

Loading

awaelchli Oct 19, 2021 •

edited

Loading