Improved docs of `Hamiltonian` and `Gradients` modules

[renatomello]

Improved documentation of the modules mentioned in the title + a faster implementation of the multikron helper function defined inside the Hamiltonian module.

Checklist:

• [x] Reviewers confirm new code works as expected.
• [x] Tests are passing.
• [x] Coverage does not decrease.
• [x] Documentation is updated.

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 99.94%. Comparing base (386fe25) to head (5b26fe6). Report is 16 commits behind head on master.

Additional details and impacted files

```diff @@ Coverage Diff @@ ## master #1428 +/- ## ======================================= Coverage 99.94% 99.94% ======================================= Files 78 78 Lines 11309 11307 -2 ======================================= - Hits 11303 11301 -2 Misses 6 6 ``` | [Flag](https://app.codecov.io/gh/qiboteam/qibo/pull/1428/flags?src=pr&el=flags&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=qiboteam) | Coverage Δ | | |---|---|---| | [unittests](https://app.codecov.io/gh/qiboteam/qibo/pull/1428/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=qiboteam) | `99.94% <100.00%> (ø)` | | Flags with carried forward coverage won't be shown. [Click here](https://docs.codecov.io/docs/carryforward-flags?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=qiboteam#carryforward-flags-in-the-pull-request-comment) to find out more.

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[alecandido]

Unfortunately, while reduce() is definitely convenient and optimal style (because of its expressivity), I believe you won't get any performance boost, since it should be a very similar for loop under the hood (possibly a recursion, but that would be worse in Python... - unless it is tail-call optimized individually, which I really doubt...).

However, the other good reason to encourage this usage is that for other functions, you could really get a speed-up, by using the built-in reduce of NumPy universal functions, e.g. np.add.reduce(array) (in which case multikron would just be an alias). Unfortunately, np.kron is not a universal function (and it can't be, because it's not acting element-wise - so you would really need multikron to be implemented in NumPy, otherwise this is the best you can do).

[renatomello]

Unfortunately, while reduce() is definitely convenient and optimal style (because of its expressivity), I believe you won't get any performance boost, since it should be a very similar for loop under the hood (possibly a recursion, but that would be worse in Python... - unless it is tail-call optimized individually, which I really doubt...).

However, the other good reason to encourage this usage is that for other functions, you could really get a speed-up, by using the built-in reduce of NumPy universal functions, e.g. np.add.reduce(array) (in which case multikron would just be an alias). Unfortunately, np.kron is not a universal function (and it can't be, because it's not acting element-wise - so you would really need multikron to be implemented in NumPy, otherwise this is the best you can do).

In [11]: from functools import reduce
    ...: from itertools import product
    ...: 
    ...: import numpy as np
    ...: 
    ...: from qibo import matrices
    ...: 
    ...: 
    ...: def multikron(matrix_list):
    ...:     h = 1
    ...:     for m in matrix_list:
    ...:         h = np.kron(h, m)
    ...:     return h
    ...: 
    ...: def new_multikron(matrix_list):
    ...:     return reduce(np.kron, matrix_list)
    ...: 
    ...: single_paulis = [matrices.I, matrices.X, matrices.Y, matrices.Z]
    ...: 
    ...: for nqubits in [2, 3, 4, 5]:
    ...:     for func in [multikron, new_multikron]:
    ...:         print(f"nqubits: {nqubits}, func: {func.__name__}")
    ...: 
    ...:         matrix_list = np.asarray(list(product(single_paulis, repeat=nqubits)))
    ...:         indexes = np.random.choice(range(4**nqubits), size=4, replace=False)
    ...:         for row in matrix_list[indexes]:
    ...:             %timeit func(row)
    ...:         print()
    ...: 
nqubits: 2, func: multikron
36.5 μs ± 270 ns per loop (mean ± std. dev. of 7 runs, 10,000 loops each)
36.5 μs ± 57.4 ns per loop (mean ± std. dev. of 7 runs, 10,000 loops each)
36.4 μs ± 76.8 ns per loop (mean ± std. dev. of 7 runs, 10,000 loops each)
36.5 μs ± 76.3 ns per loop (mean ± std. dev. of 7 runs, 10,000 loops each)

nqubits: 2, func: new_multikron
18.4 μs ± 65.1 ns per loop (mean ± std. dev. of 7 runs, 100,000 loops each)
19.6 μs ± 405 ns per loop (mean ± std. dev. of 7 runs, 100,000 loops each)
19.9 μs ± 884 ns per loop (mean ± std. dev. of 7 runs, 100,000 loops each)
19.1 μs ± 1.06 μs per loop (mean ± std. dev. of 7 runs, 100,000 loops each)

nqubits: 3, func: multikron
55 μs ± 427 ns per loop (mean ± std. dev. of 7 runs, 10,000 loops each)
54.4 μs ± 158 ns per loop (mean ± std. dev. of 7 runs, 10,000 loops each)
54.4 μs ± 167 ns per loop (mean ± std. dev. of 7 runs, 10,000 loops each)
54.7 μs ± 191 ns per loop (mean ± std. dev. of 7 runs, 10,000 loops each)

nqubits: 3, func: new_multikron
35.9 μs ± 434 ns per loop (mean ± std. dev. of 7 runs, 10,000 loops each)
36.4 μs ± 858 ns per loop (mean ± std. dev. of 7 runs, 10,000 loops each)
35.6 μs ± 535 ns per loop (mean ± std. dev. of 7 runs, 10,000 loops each)
36.3 μs ± 389 ns per loop (mean ± std. dev. of 7 runs, 10,000 loops each)

nqubits: 4, func: multikron
80 μs ± 5.24 μs per loop (mean ± std. dev. of 7 runs, 10,000 loops each)
76.3 μs ± 5.42 μs per loop (mean ± std. dev. of 7 runs, 10,000 loops each)
77.4 μs ± 2.96 μs per loop (mean ± std. dev. of 7 runs, 10,000 loops each)
76.9 μs ± 2.89 μs per loop (mean ± std. dev. of 7 runs, 10,000 loops each)

nqubits: 4, func: new_multikron
55.9 μs ± 1.44 μs per loop (mean ± std. dev. of 7 runs, 10,000 loops each)
54.2 μs ± 890 ns per loop (mean ± std. dev. of 7 runs, 10,000 loops each)
54.5 μs ± 423 ns per loop (mean ± std. dev. of 7 runs, 10,000 loops each)
55 μs ± 530 ns per loop (mean ± std. dev. of 7 runs, 10,000 loops each)

nqubits: 5, func: multikron
95.9 μs ± 1.27 μs per loop (mean ± std. dev. of 7 runs, 10,000 loops each)
99.7 μs ± 4.35 μs per loop (mean ± std. dev. of 7 runs, 10,000 loops each)
101 μs ± 3.67 μs per loop (mean ± std. dev. of 7 runs, 10,000 loops each)
99.1 μs ± 1.87 μs per loop (mean ± std. dev. of 7 runs, 10,000 loops each)

nqubits: 5, func: new_multikron
78.8 μs ± 694 ns per loop (mean ± std. dev. of 7 runs, 10,000 loops each)
78 μs ± 1.09 μs per loop (mean ± std. dev. of 7 runs, 10,000 loops each)
76.9 μs ± 943 ns per loop (mean ± std. dev. of 7 runs, 10,000 loops each)
78.5 μs ± 2.82 μs per loop (mean ± std. dev. of 7 runs, 10,000 loops each)

[alecandido]

Testing on small samples might be deceptive.

time-kron.zip

[renatomello]

Testing on small samples might be deceptive.

time-kron.zip

So it is faster for smaller $n$ and the same scaling for bigger $n$ and somehow that's a bad thing?

[alecandido]

So it is faster for smaller n and the same scaling for bigger n and somehow that's a bad thing?

@renatomello I've never said it's a bad thing. Please, do not make inference about missing statements. It's just marginal, since it's only relevant up to 4-5 qubits (where the difference is ~20%, on a small operation).

If you want to find a "bad" part (i.e. whatever I was trying to make more precise), it is:

• a faster implementation of the multikron helper function

which is quite a misleading description. The core of the operation is an array product, which is unchanged. The same optimization you gained here it could be obtained in many different places in Qibo - especially saving less redundant information, and using fewer classes - since it's just related to a Python overhead.

However, it's not worth investing, because it is not giving any significant advantage for most use cases - the overhead is only significant for operations with ~<5 qubits. Already, for ~10 qubits, the array operations are always more relevant.

Nevertheless, as I said in the first place, it is good to improve readability and maintainability of the code. Using more expressive syntax is part of the game, and that's the main advantage of the new multikron - which I acknowledged immediately.