Consider adding a global overview "map" image

[julenl]

What should we add?

During my learning process for nature I often found the challenge of connecting the dots.

From my personal perspective, simulations in nature involve multiple levels of understanding:

• Understanding the math/physics behind the process (VQE, ...), and the analytical workflow
• Understanding the different classes in qiskit and nature, how they fit together and how to put them together into a procedural workflow (script)

There is already a fairly good documentation for both of them, but I would personally find it very convenient to have a visual map that puts them in superposition, together with short non technical hints.
This would be very convenient to i.e.:

1. Speed up the understanding of the workflow
2. Understanding the different options and concepts behind each part
3. Quickly (and roughly) understanding what is going on (mathematically) behind each component without having to read the whole literature and source code
4. Identifying where does operation X occur or parameter Y get defined, in a quicker way
5. Be used as a reference "map" for orientation within the process and referencing components in a simple way

I made a simple "initial guess" draft image, that could (should) be extended and potentially corrected.
The whole content has been done by me, based on the documentation, the review of Tilly et al. on VQE, some github comments and the kind explanations of @woodsp-ibm . I did the illustrative quantum computer image with blender.

Further improvements could include clickable links to the API documentation of each component and more illustrative images and math expressions.
In my opinion, the size could be quite big, to fit as much information as possible on a single image and use it as a cheat sheet on a large monitor, or printed on an A3 paper and put on the wall of the office, as some of us do/did with the periodic table :)

Although some experienced people might find it oversimplified or unnecessary, I would have personally found something like this really useful, especially when I got started.

What do you think about it?

[mrossinek]

Hi @julenl, please excuse the late reply!

First of all, thank you very much for raising this very important documentation suggestion! I absolutely agree, that we are lacking a "bigger picture" overview which details how all the moving parts which are scattered across the Qiskit ecosystem fit together. As you probably have realized when putting this together yourself, this undertaking is not an easy task!

The best explanation which I can give for the lack of this, is the fast pace at which Qiskit and Qiskit Nature have refactored the various involved components. That as well as the limited time of all the maintainers has resulted in the current state of the documentation.

In fact, there are even more impending changes with respect to the algorithms module (see here Qiskit/RFCs#44) which is the main reason for my late reply. This still leaves some uncertainties with respect to Qiskit Nature's algorithms module and makes me hesitate in adding such an overview right now.

---

That said, let me provide some immediate feedback to your map.

I think, in its current form this is not something we can include in the main documentation. It being a graphic that to me seems to be put together completely manually, keeping it updated as things change will be very hard to achieve. The only way in which I see this being possible is if it were some sort of LaTeX or SVG file which can be properly version controlled and edited in "plain text" (so varying degree of course).

Furthermore, your graphic focusing on a very particular use case of Qiskit Nature (the electronic structure stack). While this is good as an example, I think a bigger picture overview should start with a more abstract overview of the interfaces and then provide one or two detailed examples in separate form.

And finally, although this is my personal opinion, I find the graphic fairly busy and hard to follow. I would suggest to avoid so many overlapping arrows, varying font sizes and styles, and try to rearrange things such that one can follow the "main" path of the purple arrows a more natural flow order (for example starting at the top left rather that top right; and then maybe following a clockwise circular motion).

---

To wrap up, while I definitely appreciate all the effort you have put into creating this, I do not think that we can include it in its current form (nor at the current time) in the Qiskit Nature documentation. But if you can find a way to host this and keep it up-to-date in another location (some private Github repo or some website) we can add a link to that in the documentation 👍

[julenl]

Thanks @mrossinek !
Yeah... I totally agree with you.
I initially tried to build the picture automatically using plantuml for a poster I did, but the result was not so nice visually. "My approach" focused on simplifying, without adding all the possible attributes and methods for each class, because the thing can get very overwhelming after just a few classes.
I also thought of focusing on a single case, rather than the whole landscape of possibilities, for the same reason.
At this point, I'll focus on some more important issues, and I might come back to this at some point, once the code structure stabilizes and I understand it a little better.