FAQ: What types does my pullback need to accept? #428
Conversation
Codecov Report
@@ Coverage Diff @@
## master #428 +/- ##
=======================================
Coverage 92.37% 92.37%
=======================================
Files 14 14
Lines 787 787
=======================================
Hits 727 727
Misses 60 60 Continue to review full report at Codecov.
|
| In many cases these all all tangents can be treated the same: tangent types overload a bunch of linear-operators, and the majority of functions used inside a pullback are linear operators. | ||
| If you find linear operators from Base/stdlibs that are not supported, consider openning an issue or PR on the [ChainRulesCorejl repo](https://github.com/JuliaDiff/ChainRulesCore.jl/). | ||
|
|
||
| ### Natural tangents |
There was a problem hiding this comment.
Not objecting to adding this, but don't we already say what the differences between natural and structural tangents are somewhere in the docs?
There was a problem hiding this comment.
In the design docs we probably do.
I am in-favour of having redundancy in the docs.
It makes them much more understandable, since noone reads them end-to-end.
Albeit, at the cost of making the docs harder to maintain.
| They can be thought of as a wrapper of the value the computation returns. | ||
| In this sense they wrap either a natural or structural tangent. | ||
|
|
||
| !!! warning "You should to support AbstractThunk inputs even if you don't use thunks" |
There was a problem hiding this comment.
| !!! warning "You should to support AbstractThunk inputs even if you don't use thunks" | |
| !!! warning "You should support `AbstractThunk` inputs even if you don't use thunks" |
There was a problem hiding this comment.
This headings of admonitions don't support markdown, as I recall
docs/src/writing_good_rules.md
Outdated
| Natural tangent types are the types you might feel the tangent should be. | ||
| These are a purely human notion, they are the types the user wants to use because they make the math easy. |
There was a problem hiding this comment.
I think this is a bit vague. Even if you don't provide an all-encompassing definition, you need to tell the reader roughly what you mean by "natural" at all, what distinction are you drawing? If they don't already know then all these disclaimers are pretty confusing.
I would do this by example. The simplest one would be ComplexF64, that's a struct, and by "natural" you mean a gradient which is another number, as opposed to "structural" you mean Tangent{Complex}(...). And after that, move on to more complicated ones.
There was a problem hiding this comment.
Are there not several examples in the next paragraph?
There was a problem hiding this comment.
There are, but you don't quite spell out what this word "natural" is being used to mean, before using it a bunch of times. I think that should go first: first define the terminology, then the clear-cut cases on both sides, then the tricky cases.
I mean, maybe this is done elsewhere, and the FAQ is revision... I don't have the global view clearly in my head.
Co-authored-by: willtebbutt <[email protected]>
Co-authored-by: Miha Zgubic <[email protected]>
|
In the interest of, subideal docs are better than no docs, |
There is probably a better place for this than the FAQ