JuliaDiff / JuliaDiff/ChainRules.jl

Changes to Docs

Open
#155 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

good first issue
Dominant language
Julia
Stars
475
Forks
98
PR merge metrics
No merged PRs in 30d

Description

Lots has changed since the docs were first written. #152 addresses a number of things, but there are a few more things that we might want to consider:

  • changing all references to autodiff / automatic differentiation to AD / algorithmic differentiation, with a terminology box in the docs somewhere, explaining what we're on about.
  • In the "On writing good rrule and frule " bit, we should consider modifying the recommendations for Zero() or One(). In particular, removing any mention of One because it's not generally appropriate or helpful. Additionally, the "Write Tests" section should probably be entitled "Write Tests using FiniteDifferences". Similarly, the "CAS Systems are your friends" should have some reference to them not being helpful when writing tests for derivatives.

Additionally, the section of the docs on Differentials needs to be expanded / modified to make the following points:

  • is the only operation guaranteed to be defined on differentials and, moreover, it's only guaranteed to be defined between differentials that are valid for the same primal type.
  • is only guaranteed to be defined between scalars and differentials. You can't generally multiple a differential by another differential
  • between primals and differentials isn't always defined, but it is for a lot of interesting cases e.g. Real, Matrix{<:Real} etc
    stuff that I've missed that we've figured out since this section was last written.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by locating the documentation sections on autodiff terminology, writing good rrule and frule methods, and Differentials, then compare the related changes in issue #152. Done means the terminology, testing guidance, Zero/One recommendations, CAS caveats, and differential operation guarantees are updated consistently throughout the docs.

Written by the indexing model from the issue text.

Assessment

Tech stack
julia
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.