update installation section

[Edoardo-Pedicillo]

Add a section to the documentation that explains how to install Qibo-cal and -lab with the drivers, specifying the compatible Qibolab version.
This section should be helpful for new joiners, as we have observed that the installation procedure is not always smooth and well-documented.

[alecandido]

In principle, for a vanilla installation, you should just run pip install qibocal, nothing more.

However, I acknowledge that with drivers is more complicated, because of qibolab extra dependencies. In that case, the best advice is most likely pip install qibolab[ex,tra,s,...] qibocal (which extras are required should be specified in the platforms' READMEs).

[andrea-pasquale]

However, I acknowledge that with drivers is more complicated, because of qibolab extra dependencies. In that case, the best advice is most likely pip install qibolab[ex,tra,s,...] qibocal (which extras are required should be specified in the platforms' READMEs).

For sure the part where you need to select the corresponding drivers is not trivial, many people that were starting face problems because of this.
A good step in the right direction will be to complete qiboteam/qibolab_platforms_qrc#163
It will be also interesting to have some sort of automated mechanism that can maybe check for the corresponding dependencies when running something on a platform and install them if they are not present. I don't know which module should handle it...

[alecandido]

It will be also interesting to have some sort of automated mechanism that can maybe check for the corresponding dependencies when running something on a platform and install them if they are not present. I don't know which module should handle it...

Well, we could have a requirements.txt file instead of listing the extra in the README.md.
It will always look like:

qibolab[ex,tra,s,..]

and nothing else (until when we'll support external drivers, in which case you could list further packages in there).

However, environments are tricky beasts, so I'd avoid automating too much, to avoid automatic breaking...
But I agree there should be some standard way of looking up deps for platforms. The most effective proposal I have in mind is still a standard section in platforms' README.md, but I'm open to other proposals as well.

[Edoardo-Pedicillo]

The most effective proposal I have in mind is still a standard section in platforms' README.md, but I'm open to other proposals as well.

I'm not certain about this. With your proposal, we will end up with duplicated information, with just minor changes.
This may not be the most maintainable solution.
Additionally, we should take into account that some users may prefer to use Qibocal and install the other packages directly with pip (without cloning qibolab_platform_qrc). For them, navigating to the Github repositories to look for information might not be so intuitive.
A possible solution is to update the installation section https://qibo.science/qibocal/stable/getting-started/installation.html

[alecandido]

I thought you misunderstood my proposal. I'm not suggesting to duplicate any information, but just to list the suitable qibolab extras in each platform.

A possible solution is to update the installation section qibo.science/qibocal/stable/getting-started/installation.html

This is not something you can list in the general instructions. Unless you instruct the user to always install all possible extra dependencies, whatever platform you want to use. (I.e. given Qibocal docs, and the platform files, how do you know which are the qibolab extras you need? Of course, you could inspect the platforms' imports, and the content of Qibolab's pyproject.toml, that's what we're doing - but maybe it's not the most friendly guide for a user...)

So, the README section I have in mind is:

## Qibolab extras

This platform requires `qm` and `twpas` extra.

or as a bulleted list, if you prefer.

In principle, you could even replace it by:

## Dependencies installation

```sh
pip install qibolab[qm, twpas]
```

which would duplicate the pip install qibolab[] characters, but it's a price I'd be willing to pay...

In any case, in the general instructions, you would add a "read the platform" comment, and possibly an explanation. But this should be done in Qibolab, and just linked in Qibocal.

Additionally, we should take into account that some users may prefer to use Qibocal and install the other packages directly with pip (without cloning qibolab_platform_qrc). For them, navigating to the Github repositories to look for information might not be so intuitive.

Here I may be the one not understanding, since I can't make sense of this part.

If you don't need to use a platform, you don't need to clone the platforms' repo (nor manually copy, fwiw...). But then all you need is pip install qibocal, and nothing else (no platform, no extra deps - dummy is being installed automatically as a dependency).

All the problem arises because you actually want to use a platform, and since you're not writing it (otherwise you'd read the Qibolab docs, and possibly understand the role of extra dependencies - assuming we wrote it there) you definitely need to take it from somewhere. I.e. you either clone or navigate.

P.S.: by platforms' README.md I mean the now missing qibolab_platforms_qrc/qw11q/README.md and analogues

[andrea-pasquale]

My only worry with this approach is that if you do naively pip install qibolab[...] after you do pip install qibocal you might install a version of qibolab which is not compatible with qibocal... which is something that already happened in the past.
It could also happen now was well since if you do pip install qibocal you will install qibolab 0.1.* while if you later do pip install qibolab[...] you are going to install qibolab 0.2.
In a certain way qibocal should be aware of the extras dependencies in qibolab to avoid these type of scenarios.
I don't have a clear solution in mind if not porting all extra deps in qibolab as extra deps in qibocal, or do some sort of mapping between the two, which in any case will result in a duplication of the information.

[alecandido]

It could also happen now was well since if you do pip install qibocal you will install qibolab 0.1.* while if you later do pip install qibolab[...] you are going to install qibolab 0.2.

That's why I was proposing to install first Qibolab, then Qibocal. Or the two of them in the same command, in case pip will resolve them together.

In a certain way qibocal should be aware of the extras dependencies in qibolab to avoid these type of scenarios.
I don't have a clear solution in mind if not porting all extra deps in qibolab as extra deps in qibocal, or do some sort of mapping between the two, which in any case will result in a duplication of the information.

Yes, this is what I had in mind since the beginning. I'm not sure it's even possible - because extras could group existing dependencies, but you should not be able to have different versions of the same, including different combinations of its extras. But even if it is, I'm pretty sure I'd like to avoid...

The other option could be to first install Qibocal, work out which is the installed Qibolab version, and then install Qibolab specifying both the extras and the same version is already installed, like:

pip install qibocal
# find out qibolab installed version, x.y.z
pip list | grep qibolab
# fix qibolab version to x.y.z
pip install qibolab[ex,tra,s,...]==x.y.z

But it's definitely more cumbersome...

[Edoardo-Pedicillo]

Thanks @alecandido, now your idea is clear and I agree.
Since there is an issue in qibolab_platform_qrc I will close this issue.