UTF8 Documentation rework #104

kellertuer · 2020-01-25T18:47:55Z

Works on #101 and introduces a notation overview. Here's the current details

We can not to anything against

\mathrm{M}, \mathrm{H}, \mathrm{T} (for the Minkowski-norm, Hermitian and transposed vectors),...
the same for \operatornames
\lvert and \rvert (as well as \lVert and \rVert) are hard to replace, since the utf8 symbols (| and ‖) have in TeX a different spacing

I replaced

all manifolds (M, \mathcal M) in math mode with ℳ
\langle, \rangle with their utf8s ⟨⟩
\cdot with
\ldots with
\times with ⨉

I noticed that the links to allocate, allocate_resultandnumber_eltypereturn warnings – are they properly exported in ManifoldsBase`?

Within the table on notations.md on my machine it seems random whether math is recognized or not... can someone verify that? My change from $ to `` dioes only randomly take effect.

What do you think to the proposed notation? Some of that is really not unified currently (especially dot/inner and (co)tangents).

kellertuer · 2020-01-25T19:05:28Z

A first note is – despite the notation.md rendering all renders fine on safari. Concerning the unified notation, I'd like some feedback on what we agree – document that in notation.md and then unify the decstrings accordingly.

src/statistics.jl

mateuszbaran · 2020-01-25T19:52:55Z

It looks quite nice in github file preview. I'll check it more closely later.

I noticed that the links to allocate, allocate_resultandnumber_eltypereturn warnings – are they properly exported in ManifoldsBase`?

allocate and number_eltype are exported in both ManifoldsBase and Manifolds. I don't know why there are warnings.

What do you think to the proposed notation? Some of that is really not unified currently (especially dot/inner and (co)tangents).

It's OK. One small issue is that I'm used to denoting tangent vectors by lower case letters (u, v, w) but I can use your notation here.

kellertuer · 2020-01-25T20:58:11Z

It's OK. One small issue is that I'm used to denoting tangent vectors by lower case letters (u, v, w) but I can use your notation here.

i am not saying my proposal should definetly stay unchanged, it's just close to what I am used to (despite that we currently write ( , )_x for the inner product since theres also a dual pairing between tangent and cotangent). I do think it's nicer to have different sets for points & tangents.

codecov · 2020-01-25T21:44:35Z

Codecov Report

Merging #104 into master will not change coverage by %.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #104   +/-   ##
=======================================
  Coverage   94.29%   94.29%           
=======================================
  Files          44       44           
  Lines        2715     2715           
=======================================
  Hits         2560     2560           
  Misses        155      155

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 4bef2c9...4bef2c9. Read the comment docs.

sethaxen

Thanks for getting started on this! I have a few general comments.
Set notation, greek letters, and arrows can be converted to unicode equivalents.
RE × and ∘, these sometimes end up looking really cramped. This is especially the case for the latter, which is why I didn't end up using it.
I personally don't like the look of the script characters, which are much more slanted than their equivalent mathcal.
There are a number of places where the old latex forms are still used. I noted a few but not all of them; you may need to grep to make sure none were missed.

docs/src/manifolds/product.md

docs/src/manifolds/symmetricpositivedefinite.md

docs/src/notation.md

src/groups/group.jl

src/groups/special_euclidean.jl

src/manifolds/CholeskySpace.jl

src/manifolds/Hyperbolic.jl

kellertuer · 2020-01-28T04:42:32Z

For the mathcals, \times and \circ I will change that back then. Yes, I was also not so happy with those after changing them.

Co-Authored-By: Seth Axen <seth.axen@gmail.com>

…folds.jl into documentation-rework

kellertuer · 2020-01-28T11:21:30Z

Sometimes markdown (especially tables) math and utf8 within that seems to work not that nicely. Then I remembered that for notations.md we never show that in REPL anyways, so for the markdown files I propose to use classical LaTeX and just for the docstrings the UTF8

kellertuer · 2020-01-28T11:22:41Z

Further, I would like to unify notations, the table is my proposal of what I noticed, feel free to suggest further notations and check whether you agree with my proposal. We can of course discuss, With a finished unified notation I would adapt the notation accordingly in the docstrings, where we currently have 3-4 different notations.

Co-Authored-By: Seth Axen <seth.axen@gmail.com>

…folds.jl into documentation-rework

kellertuer · 2020-02-04T10:01:24Z

Thanks for so carefully revising my proposed unification. It was actually some work; after finishing here I will to the same to base, also introducing code blue there'n stuff. I think I already reworked all your changes – noticed that the proposed changes (thanks for directly doing those) can be batch-commited when going through them in the files changed tab :)

Just two questions remain I think

Our differential notation from Rotations and the group manifolds

Our translation notation τ from group manifolds

Can you elaborate on those two? I added \circ to the notations. Is that what you meant with the first? The τ I could not find within notations for group manifolds.

…on`.

…icManifold to pass down only the mutating version of exp, since we do the same for log.

…log!

…or other than the default metric one has to provide an implementation.

sethaxen · 2020-02-04T22:53:12Z

Thanks for so carefully revising my proposed unification.

Thanks for doing this!

Just two questions remain I think

Our differential notation from Rotations and the group manifolds

Our translation notation τ from group manifolds

Can you elaborate on those two? I added \circ to the notations. Is that what you meant with the first? The τ I could not find within notations for group manifolds.

\circ in the notations is nice. There are also other operations that could go there in addition to the inner product, e.g. \times as a Cartesian product.

What I meant here was the differential in the sense used for translate_diff and apply_diff. It would be nice if we gave a more precise definition, but I think here it's just important to note the notation.

Also τ appears as a generalization of L and R, the left or right translations. It appears in

but it is used extensively in docstrings in #96. We should probably use it more extensively in translate, inverse_translate, apply, etc. If you'd prefer, I could handle this docstring update in #96 once this is merged.

I'll continue the review where I left off yesterday.

sethaxen

Whew! Okay I noted a bunch more changes. Some of them appear in more places including lines not yet edited, so I'll list some general observations here:

We need notation for basis vectors (and potentially separately for Ξ if not the same)
Notation for coefficients of a tangent vector in a basis (we sometimes use X^i, which I like)
We sometimes use tr and sometimes trace for trace, we should pick one
There are a number of places where v was changed to X, but the norm or square, for example, of X still has v in the name, so that the code is harder to follow I noted a few, but there were more. (e.g. vout).
transpose and conjugate transpose are both still missing from notations table (see previous review)
identity matrix and zero matrix should be in the notation table, and we should choose a convention whether they are bold or non-bold, mathrm or not (see e.g. Stiefel and Rotations). I generally like them non-bold and non mathrm.
"eminating" was in a bunch of places and should be "emanating" everywhere
\exp_pX -> \exp_p X for clarity. Likewise \log_pq -> \log_p q.

I probably won't have the time to review again for a few days, so I'll mark approved, and feel free to merge when you are satisfied. Thanks again!

docs/src/notation.md

sethaxen · 2020-02-04T22:59:24Z

docs/src/notation.md

+| $\mathcal M$ | a manifold | $\mathcal M_1, \mathcal M_2,\ldots,\mathcal N$ | |
+| $\operatorname{Exp}$ | the matrix exponential | |
+| $\operatorname{Log}$ | the matrix logarithm | |
+| $\mathcal P_{q\gets p}X$ | parallel transport | | of the vector $X$ from $T_p\mathcal M$ to $T_q\mathcal M$


Can you explain the use of this notation vs P_{p \to q} ? The latter seems to read better to me.

Thats easy, if you concatenate parallel transports $P_{q\gets p}P_{p\gets s}X$, i.e. you transport X from s -> p -> q this version is far better readable than $P_{p\to q}P_{s\to p}$ since for this the order is obscured. The first one can be read just from right to left.

src/manifolds/ProductManifold.jl

src/manifolds/Rotations.jl

src/manifolds/SymmetricPositiveDefiniteLinearAffine.jl

src/manifolds/SymmetricPositiveDefiniteLogCholesky.jl

src/orthonormal_bases.jl

src/statistics.jl

sethaxen · 2020-02-04T23:45:00Z

src/statistics.jl

    ytmp = copy(yold)
-    v = zero_tangent_vector(M, y)
+    v = zero_tangent_vector(M, q)


v to X in this file. Probably useful to change x to p as elsewhere to avoid confusion.

I left x when it was a vector of points on the manifold. but I changed x0 to p0.

…correct emanating.

… to the notations table.

Co-Authored-By: Seth Axen <seth.axen@gmail.com>

…folds.jl into documentation-rework # Conflicts: # src/manifolds/Sphere.jl # src/manifolds/Stiefel.jl

kellertuer · 2020-02-05T09:13:37Z

Additionally to $\times$ I also added $\hat$ for the Cartesian (n-ary) power.

It would be great if you could add $\tau$ within your #96 then, when you use
it from then on more often anyways.

I tried to find further v-resemblemses not that I also did not (xet) rename
all tests and their variables.

For the matrices I also prefer non-bold non-mathrm, just $0_k$ and $I_k$ and added that to the notations as well.

Basis vectors are just $\Xi = {X_1,\ldots,X_n}$, i.e. $\Xi$ is a set of vectors, maybe a basis. I thought we use $X_1$ and $X^1$ more like depending on the Einstein summation? This might not yet be fully unified.

Finally, I don't know how I came to "eminating" I corrected those occurences.

I will keep this one open a day or two just to give everybody a possibility to take a final look.

mateuszbaran · 2020-02-05T09:45:18Z

docs/src/notation.md

+| $^{\wedge}$ | (n-ary) Cartesian power of a manifold | | see [`PowerManifold`](@ref) |
+| $T^*_p \mathcal M$ | the cotangent space at $p$ | | |
+| $\xi$ | a cotangent vector from $T^*_p \mathcal M$ | $\xi_1, \xi_2,\ldots,\eta,\zeta$ | sometimes written with base point $\xi_p$. |
+| $n$ | dimension (of a manifold) | $n_1,n_2,\ldots,m, \operatorname{dim}(\mathcal M)$| for the real dimension sometimes also $\operatorname{dim}_{\mathbb R}(\mathcal M)$|


In docstrings \dim is used instead of \operatorname{dim}. Is this due to a documentation rendering issue?

It's mainly due to me having missed to replace those, after I noticed \dim is available. I replaced those two, too, now.

src/manifolds/PowerManifold.jl

kellertuer added 6 commits January 25, 2020 19:44

update documentation to use more utf8, especially in math.

436eb29

update documentation, where this might not be that useful.

fade359

Adds a notation page.

8fca61f

\circ -> ⚬

ed6a6f1

fixes circ, since I mistakenly took the wrong circ.

5f00666

refactors a few further M.

8ab0928

mateuszbaran reviewed Jan 25, 2020

View reviewed changes

src/statistics.jl Outdated Show resolved Hide resolved

removes a spurious 𝒩.

ed30878

sethaxen requested changes Jan 27, 2020

View reviewed changes

kellertuer and others added 13 commits January 28, 2020 05:49

Update docs/src/notation.md

103f773

Co-Authored-By: Seth Axen <seth.axen@gmail.com>

Update src/manifolds/Hyperbolic.jl

4bbd3da

Co-Authored-By: Seth Axen <seth.axen@gmail.com>

replaces \gets with ←

ffdcb35

Merge branch 'documentation-rework' of github.com:JuliaNLSolvers/Mani…

9bac84d

…folds.jl into documentation-rework

\dots to …

3cfa995

Replaces \to with → in docstrings.

7aba7f8

Replace greek letters.

b0db476

Replaces \in \neq and \colon with their utf8s.

ab8dc0e

Changes lfloor and lfloor to their utf8s.

783cebb

revert ⨉ back to \times.

7427d2a

revert ◦ back to \circ.

adf01f7

removes double-mentioned functions.

eadf25a

Fixes the notations table.

c7e8bbf

Fixes a copy-paste-error.

e87d942

kellertuer and others added 6 commits February 4, 2020 10:33

Return from caligraphic UTF8 to $\mathcal ...$

4224994

replace \partial with ∂.

21837c3

Apply suggestions from code review

ddd69b3

Co-Authored-By: Seth Axen <seth.axen@gmail.com>

Replace \Gamme with Γ.

59be2b2

update \dim.

2a10ef7

Merge branch 'documentation-rework' of github.com:JuliaNLSolvers/Mani…

fcd9977

…folds.jl into documentation-rework

kellertuer added 6 commits February 4, 2020 11:08

use \dim more consistently throughout the docs of `manifold_dimensi…

e1c06b0

…on`.

rename B.v to B.frame_direction in the DiagonalizingONB.

07f25b7

adds a few test cases, rename B.v to B.frame_direction and unify Metr…

3f72d23

…icManifold to pass down only the mutating version of exp, since we do the same for log.

fixes documentation for project tangent on the circle and adds a test.

8c9cca5

unify Metric Manifold to not implement exp/log neither but only exp!/…

102c755

…log!

Fixes a typo in MetricManifolds log documentation and explains that f…

0be2cf3

…or other than the default metric one has to provide an implementation.

sethaxen approved these changes Feb 4, 2020

View reviewed changes

kellertuer and others added 7 commits February 5, 2020 08:11

change vout to Y, introduce Cartesian product and power to notation, …

d20ab25

…correct emanating.

unifies spacing in math formulae, trace to tr, and adds further terms…

92940a7

… to the notations table.

Apply suggestions from code review

b06cad5

Co-Authored-By: Seth Axen <seth.axen@gmail.com>

apply the remaining changes from review.

741085b

Finalize notations.md.

e7bba5c

Merge branch 'documentation-rework' of github.com:JuliaNLSolvers/Mani…

64f798f

…folds.jl into documentation-rework # Conflicts: # src/manifolds/Sphere.jl # src/manifolds/Stiefel.jl

Fixes a final typo.

fcb4895

mateuszbaran reviewed Feb 5, 2020

View reviewed changes

mateuszbaran approved these changes Feb 5, 2020

View reviewed changes

unifies usage of \dim.

4e21e0e

mateuszbaran reviewed Feb 5, 2020

View reviewed changes

src/manifolds/PowerManifold.jl Outdated Show resolved Hide resolved

updates another docstring.

4bef2c9

kellertuer merged commit a56963f into master Feb 5, 2020

kellertuer deleted the documentation-rework branch February 5, 2020 18:00

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

UTF8 Documentation rework #104

UTF8 Documentation rework #104

kellertuer commented Jan 25, 2020

kellertuer commented Jan 25, 2020

mateuszbaran commented Jan 25, 2020

kellertuer commented Jan 25, 2020

codecov bot commented Jan 25, 2020 •

edited

Loading

sethaxen left a comment

kellertuer commented Jan 28, 2020

kellertuer commented Jan 28, 2020

kellertuer commented Jan 28, 2020

kellertuer commented Feb 4, 2020

sethaxen commented Feb 4, 2020

sethaxen left a comment

sethaxen Feb 4, 2020

kellertuer Feb 5, 2020

sethaxen Feb 4, 2020

kellertuer Feb 5, 2020

kellertuer commented Feb 5, 2020

mateuszbaran Feb 5, 2020

kellertuer Feb 5, 2020

UTF8 Documentation rework #104

UTF8 Documentation rework #104

Conversation

kellertuer commented Jan 25, 2020

kellertuer commented Jan 25, 2020

mateuszbaran commented Jan 25, 2020

kellertuer commented Jan 25, 2020

codecov bot commented Jan 25, 2020 • edited Loading

Codecov Report

sethaxen left a comment

Choose a reason for hiding this comment

kellertuer commented Jan 28, 2020

kellertuer commented Jan 28, 2020

kellertuer commented Jan 28, 2020

kellertuer commented Feb 4, 2020

sethaxen commented Feb 4, 2020

sethaxen left a comment

Choose a reason for hiding this comment

sethaxen Feb 4, 2020

Choose a reason for hiding this comment

kellertuer Feb 5, 2020

Choose a reason for hiding this comment

sethaxen Feb 4, 2020

Choose a reason for hiding this comment

kellertuer Feb 5, 2020

Choose a reason for hiding this comment

kellertuer commented Feb 5, 2020

mateuszbaran Feb 5, 2020

Choose a reason for hiding this comment

kellertuer Feb 5, 2020

Choose a reason for hiding this comment

codecov bot commented Jan 25, 2020 •

edited

Loading