Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Addition of generic / introductory glossary #222

Open
wants to merge 6 commits into
base: main
Choose a base branch
from

Conversation

thomasgudjonwright
Copy link
Contributor

@thomasgudjonwright thomasgudjonwright commented Sep 25, 2020

Closes #117

Please let me know where I missed the mark / could use some review!

docs/src/glossary.md Outdated Show resolved Hide resolved
@thomasgudjonwright thomasgudjonwright changed the title WIP: Initial addition of glossary Addition of generic / introductory glossary Dec 1, 2020
@thomasgudjonwright thomasgudjonwright marked this pull request as ready for review December 1, 2020 19:16
Copy link
Contributor

@BSnelling BSnelling left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This glossary is a nice addition to the docs. I think you've covered the key pieces of vocabulary and it will be useful to have them summarised conveniently in one place.

Will this glossary be its own page in the docs? In which case, you'll need to modify docs/make.jl once you know where you want it to go.

docs/src/glossary.md Outdated Show resolved Hide resolved
docs/src/glossary.md Outdated Show resolved Hide resolved

###Adjoint:

The conjugate transpose of the Jacobian for a given function `f`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the adjoint always the conjugate transpose of the Jacobian specifically? In the below definitions which reference the adjoint, it's always the "adjoint of the Jacobian".

This makes me think the adjoint definition should be "The conjugate transpose of a matrix" and the subsequent definitions can refer to "the adjoint of the Jacobian".

Alternatively if, when we mention the adjoint, we're always talking about the adjoint of a Jacobian, this definition can stay as it is and in subsequent definitions we can just say "the adjoint".

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably we want to title the Adjoint of a function.
ANd start by saying that the adjoint of a matrix is another word for it's conjugate transpose.
Then mentioning that it can also be applied to a linear operator as every linear operator can be described as y = Jx and that as an adjoint linear operator of y' = x'J'.
Then say that people say as a shorthand/abuse of terminoly the adjoint of a function,
when what they actually mean is to get a function which is the adjoint of pushfoward linear operator.
The pushforward linear operator is the the linear operator that has the same jacobian as the function at that point.
The pullback is its adjoint.
linearization of the function at a point, to get a linear operator (the pushforward),
and then
Then say that people occationally say the adjoint of a function,
when what they really mean is: the adjoint of the jacobian of the function,
or they mean the pullback.
Sometimes people say adjoint of a function to mean pullback.

Copy link
Contributor Author

@thomasgudjonwright thomasgudjonwright Dec 9, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I totally agree this def isn't sufficient. The adjoint is super broad as a term, so I am having a hard time figuring out how much / how little to include

docs/src/glossary.md Outdated Show resolved Hide resolved
docs/src/glossary.md Outdated Show resolved Hide resolved
docs/src/glossary.md Outdated Show resolved Hide resolved
docs/src/glossary.md Outdated Show resolved Hide resolved
docs/src/glossary.md Outdated Show resolved Hide resolved
docs/src/glossary.md Outdated Show resolved Hide resolved
docs/src/glossary.md Outdated Show resolved Hide resolved

####Zero:

`Zero()` can also be a differential type. If you have trouble understanding the rules enforced upon differential types, consider this one first, as `Zero()` is the trivial vector space.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this sentence is unclear

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated with more fundamental info

docs/src/glossary.md Outdated Show resolved Hide resolved
docs/src/glossary.md Outdated Show resolved Hide resolved
docs/src/glossary.md Outdated Show resolved Hide resolved
docs/src/glossary.md Outdated Show resolved Hide resolved
docs/src/glossary.md Outdated Show resolved Hide resolved
docs/src/glossary.md Outdated Show resolved Hide resolved
@oxinabox
Copy link
Member

oxinabox commented Dec 3, 2020

Nice work Tom.
Sorry it has taken so long to review it.

Thing that would really polish this would be to have cross reference links within this page for when things refer to other things.
Or really next level if we can do it across the whole of the docs for each time something is mentioned.

Also would be nice to link to wikipedia in a few things.

@nickrobinson251 nickrobinson251 added the documentation Improvements or additions to documentation label May 7, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Create glossary for terms used in the project
5 participants