Improve Quickstart: move optimizer and config sections #2608
Conversation
|
Hello. You may have forgotten to update the changelog!
|
Codecov Report
@@ Coverage Diff @@
## master #2608 +/- ##
=======================================
Coverage 99.59% 99.59%
=======================================
Files 249 249
Lines 20256 20256
=======================================
Hits 20173 20173
Misses 83 83
Continue to review full report at Codecov.
|
There was a problem hiding this comment.
Thanks @mariaschuld!
I have to admit I find this one a bit hard to review, since it is mostly on orgnanization, so I'll just leave a top-level comment.
-
Configuration: I agree this should be removed from the sidebar 👍 It was very niche, and distracted from the other entries.
However, I would also say it doesn't fit in the Circuits page?
-
It makes the circuit page very long, which negates one of the advantages of the quickstarts (they are concise reference pages)
-
I'm also not sure how important it is, and whether anyone clicking on Circuits would be interested in configuration?
Perhaps another solution would be to keep Configuration as a separate ReST page, but still remove it from the ToC. Instead, we could have a sentence in the
Circuits/Defining a Devicesection that says 'For details on saving device configurations, please see Configurations.' -
-
Optimizers: With the optimizer page, I am a bit more conflicted. I agree that it belongs to some extent within the NumPy page, since they are only applicable if you are using Autograd. On the other hand, the quantum-aware optimizers (
QNG,Rotosolve,ShotAdaptive,LieAlgebra). My condensed thoughts:-
I think are very important features, and shouldn't be so buried (at the moment, it takes 3 clicks, scrolling, and clicking on a picture of the NumPy logo to find them!).
-
I imagine that these are important enough features that users may be likely to switch from TF/Torch to Autograd to use them if they need them.
-
They are actually possible to use with JAX (but it is less trivial, you need to pass the
grad_fnmanually).
I'm not sure what the best solution is here 🤔 I think they would be good to keep them more discoverable, while also continuing to list them in the
NumPypage? -
|
Thanks for the comments. Making the config a linked but not listed stub is a great idea. About the quantum-aware optimisers, they are referenced quite prominently in the note of the Gradients and Training page, no? That would be only one click? Before, we were literally doubling up on this information: If I want to learn about how to optimise a circuit, do I go to that section or to optimizers? And then if I go to optimisers, I have to understand about interfaces to parse the list there. So I would argue they belong 100% on the Gradients and Training page? Is there any way we can make them even more prominent, but move them to the logical section? I'm sure @christina also has a good idea! |
There was a problem hiding this comment.
Thanks @mariaschuld! Looks like there are still a few links to the deleted optimizers page that Sphinx is complaining about:
Regarding doubling up on the optimizers: you are right. I just can't stop thinking that they are harder to find now than before, if you don't know where to look 🤔
Another option I can think of (that is still not perfect) is to have an 'Optimizers' subsection on the 'Gradients and Training' page, rather than a notebox, that lists the quantum aware optimizers using autosummary:
The Optimizer and Configuration sections were very sparsely populated, and I integrated them into others.