.. _cbenchmarkvectorrst:

===========================
Use of PYBIND11_MAKE_OPAQUE
===========================


.. only:: html

    **Links:** :download:`notebook <cbenchmark_vector.ipynb>`, :downloadlink:`html <cbenchmark_vector2html.html>`, :download:`PDF <cbenchmark_vector.pdf>`, :download:`python <cbenchmark_vector.py>`, :downloadlink:`slides <cbenchmark_vector.slides.html>`, :githublink:`GitHub|_doc/notebooks/cbenchmark_vector.ipynb|*`


`pybind11 <https://pybind11.readthedocs.io/>`__ automatically converts
``std::vector`` into python list. That’s convenient but not necessarily
efficient depending on how it is used after that.
`PYBIND11_MAKE_OPAQUE <https://pybind11.readthedocs.io/en/stable/advanced/cast/stl.html#making-opaque-types>`__
is used to create a
`capsule <https://docs.python.org/3/c-api/capsule.html>`__ to hold a
pointer on the C++ object.

.. code:: ipython3

    from jyquickhelper import add_notebook_menu
    add_notebook_menu()






.. contents::
    :local:





.. code:: ipython3

    %matplotlib inline

Two identical classes
---------------------

Both of then creates random vectors equivalent to
``std::vector<Tensor>``, and ``Tensor ~  std::vector<float>``. The first
one returns a capsule due
``PYBIND11_MAKE_OPAQUE(std::vector<OneTensorFloat>)`` inserted into the
C++ code. The other one is returning a list.

.. code:: ipython3

    from cpyquickhelper.examples.vector_container_python import (
        RandomTensorVectorFloat, RandomTensorVectorFloat2)
    
    rnd = RandomTensorVectorFloat(10, 10)
    result = rnd.get_tensor_vector()
    print(result)


.. parsed-literal::
    <cpyquickhelper.examples.vector_container_python.OneTensorVector object at 0x000002B144FB5470>


.. code:: ipython3

    result_ref = rnd.get_tensor_vector_ref()
    print(result_ref)


.. parsed-literal::
    <cpyquickhelper.examples.vector_container_python.TensorVectorConstReferencePointer object at 0x000002B13BB8DD70>


.. code:: ipython3

    rnd2 = RandomTensorVectorFloat2(10, 10)
    result2 = rnd2.get_tensor_vector()
    print(result2)


.. parsed-literal::
    [<cpyquickhelper.examples.vector_container_python.OneTensor2 object at 0x000002B144BC4330>, <cpyquickhelper.examples.vector_container_python.OneTensor2 object at 0x000002B144BC2BF0>, <cpyquickhelper.examples.vector_container_python.OneTensor2 object at 0x000002B144BC2E30>, <cpyquickhelper.examples.vector_container_python.OneTensor2 object at 0x000002B144BC2C30>, <cpyquickhelper.examples.vector_container_python.OneTensor2 object at 0x000002B144BC2FB0>, <cpyquickhelper.examples.vector_container_python.OneTensor2 object at 0x000002B144BC2970>, <cpyquickhelper.examples.vector_container_python.OneTensor2 object at 0x000002B144BC26F0>, <cpyquickhelper.examples.vector_container_python.OneTensor2 object at 0x000002B144BC22B0>, <cpyquickhelper.examples.vector_container_python.OneTensor2 object at 0x000002B144BC21B0>, <cpyquickhelper.examples.vector_container_python.OneTensor2 object at 0x000002B144BC20F0>]


.. code:: ipython3

    result2_ref = rnd2.get_tensor_vector_ref()
    print(result2_ref)


.. parsed-literal::
    <cpyquickhelper.examples.vector_container_python.TensorVectorConstReferencePointer2 object at 0x000002B144EE0C30>


.. code:: ipython3

    %timeit rnd.get_tensor_vector()


.. parsed-literal::
    3.13 µs ± 60.6 ns per loop (mean ± std. dev. of 7 runs, 100,000 loops each)


.. code:: ipython3

    %timeit rnd.get_tensor_vector_ref()


.. parsed-literal::
    1.21 µs ± 38.4 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)


.. code:: ipython3

    %timeit rnd2.get_tensor_vector()


.. parsed-literal::
    10.4 µs ± 138 ns per loop (mean ± std. dev. of 7 runs, 100,000 loops each)


.. code:: ipython3

    %timeit rnd2.get_tensor_vector_ref()


.. parsed-literal::
    1.19 µs ± 18.1 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)


Scenarii
--------

Three possibilities:


-  **list**: ``std::vector<Tensor>`` is converted into a list of copied
   Tensors
-  **capsule**: ``std::vector<Tensor>`` is converted into a capsule on a
   copied ``std::vector<Tensor>``, the capsule still holds the pointer
   and is responsible to the deletion.
-  **ref**: ``std::vector<Tensor>`` is just return as a pointer. The
   cost of getting the pointer does not depend on the content size. It
   is somehow the low limit.

Plots
-----

.. code:: ipython3

    import itertools
    from cpyquickhelper.numbers.speed_measure import measure_time
    from tqdm import tqdm
    import pandas
    
    data = []
    sizes = [1, 2, 5, 10, 20, 50, 100, 200, 500, 1000, 5000, 10000]
    sizes = list(itertools.product(sizes, sizes))
    for i, j in tqdm(sizes):
        if j >= 1000:
            if i > 1000:
                continue
        if i * j >= 1e6:
            repeat, number = 3, 3
        else:
            repeat, number = 10, 10
        rnd = RandomTensorVectorFloat(i, j)
        obs = measure_time(lambda: rnd.get_tensor_vector(), repeat=repeat, number=number, div_by_number=True)
        obs['name'] = 'capsule'
        obs['n_vectors'] = i
        obs['size'] = j
        data.append(obs)
    
        rnd2 = RandomTensorVectorFloat2(i, j)
        obs = measure_time(lambda: rnd2.get_tensor_vector(), repeat=repeat, number=number, div_by_number=True)
        obs['name'] = 'list'
        obs['n_vectors'] = i
        obs['size'] = j
        data.append(obs)
    
        obs = measure_time(lambda: rnd2.get_tensor_vector_ref(), repeat=repeat, number=number, div_by_number=True)
        obs['name'] = 'ref'
        obs['n_vectors'] = i
        obs['size'] = j
        data.append(obs)
        
    df = pandas.DataFrame(data)
    df.tail()


.. parsed-literal::
    100%|████████████████████████████████████████████████████████████████████████████████| 144/144 [00:19<00:00,  7.43it/s]






.. raw:: html

    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }

        .dataframe tbody tr th {
            vertical-align: top;
        }

        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>average</th>
          <th>deviation</th>
          <th>min_exec</th>
          <th>max_exec</th>
          <th>repeat</th>
          <th>number</th>
          <th>ttime</th>
          <th>context_size</th>
          <th>name</th>
          <th>n_vectors</th>
          <th>size</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>409</th>
          <td>0.018321</td>
          <td>0.000367</td>
          <td>0.018026</td>
          <td>0.018838</td>
          <td>3</td>
          <td>3</td>
          <td>0.054962</td>
          <td>64</td>
          <td>list</td>
          <td>10000</td>
          <td>200</td>
        </tr>
        <tr>
          <th>410</th>
          <td>0.000002</td>
          <td>0.000001</td>
          <td>0.000001</td>
          <td>0.000004</td>
          <td>3</td>
          <td>3</td>
          <td>0.000007</td>
          <td>64</td>
          <td>ref</td>
          <td>10000</td>
          <td>200</td>
        </tr>
        <tr>
          <th>411</th>
          <td>0.010974</td>
          <td>0.000492</td>
          <td>0.010512</td>
          <td>0.011656</td>
          <td>3</td>
          <td>3</td>
          <td>0.032923</td>
          <td>64</td>
          <td>capsule</td>
          <td>10000</td>
          <td>500</td>
        </tr>
        <tr>
          <th>412</th>
          <td>0.035484</td>
          <td>0.000900</td>
          <td>0.034286</td>
          <td>0.036456</td>
          <td>3</td>
          <td>3</td>
          <td>0.106451</td>
          <td>64</td>
          <td>list</td>
          <td>10000</td>
          <td>500</td>
        </tr>
        <tr>
          <th>413</th>
          <td>0.000003</td>
          <td>0.000002</td>
          <td>0.000001</td>
          <td>0.000005</td>
          <td>3</td>
          <td>3</td>
          <td>0.000008</td>
          <td>64</td>
          <td>ref</td>
          <td>10000</td>
          <td>500</td>
        </tr>
      </tbody>
    </table>
    </div>



.. code:: ipython3

    piv = pandas.pivot_table(df, index=['n_vectors', 'size'], columns=['name'], values='average')
    piv['ratio'] = piv['capsule'] / piv['list']
    piv.tail()






.. raw:: html

    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }

        .dataframe tbody tr th {
            vertical-align: top;
        }

        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>name</th>
          <th>capsule</th>
          <th>list</th>
          <th>ref</th>
          <th>ratio</th>
        </tr>
        <tr>
          <th>n_vectors</th>
          <th>size</th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th rowspan="5" valign="top">10000</th>
          <th>20</th>
          <td>0.001611</td>
          <td>0.009616</td>
          <td>0.000001</td>
          <td>0.167512</td>
        </tr>
        <tr>
          <th>50</th>
          <td>0.001892</td>
          <td>0.010399</td>
          <td>0.000001</td>
          <td>0.181907</td>
        </tr>
        <tr>
          <th>100</th>
          <td>0.002597</td>
          <td>0.014054</td>
          <td>0.000002</td>
          <td>0.184789</td>
        </tr>
        <tr>
          <th>200</th>
          <td>0.004847</td>
          <td>0.018321</td>
          <td>0.000002</td>
          <td>0.264565</td>
        </tr>
        <tr>
          <th>500</th>
          <td>0.010974</td>
          <td>0.035484</td>
          <td>0.000003</td>
          <td>0.309278</td>
        </tr>
      </tbody>
    </table>
    </div>



.. code:: ipython3

    import matplotlib.pyplot as plt
    fig, ax = plt.subplots(1, 2, figsize=(10, 4))
    piv[['capsule', 'list', 'ref']].plot(logy=True, ax=ax[0], title='Capsule (OPAQUE) / list')
    piv.sort_values('ratio', ascending=False)[['ratio']].plot(ax=ax[1], title='Ratio Capsule (OPAQUE) / list');



.. image:: cbenchmark_vector_16_0.png


.. code:: ipython3

    flat = piv.reset_index(drop=False)[['n_vectors', 'size', 'ratio']]
    flat_piv = flat.pivot('n_vectors', 'size', 'ratio')
    flat_piv






.. raw:: html

    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }

        .dataframe tbody tr th {
            vertical-align: top;
        }

        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th>size</th>
          <th>1</th>
          <th>2</th>
          <th>5</th>
          <th>10</th>
          <th>20</th>
          <th>50</th>
          <th>100</th>
          <th>200</th>
          <th>500</th>
          <th>1000</th>
          <th>5000</th>
          <th>10000</th>
        </tr>
        <tr>
          <th>n_vectors</th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>1</th>
          <td>0.566917</td>
          <td>1.130723</td>
          <td>0.995022</td>
          <td>1.023320</td>
          <td>1.028793</td>
          <td>1.612390</td>
          <td>0.943035</td>
          <td>1.717130</td>
          <td>1.284653</td>
          <td>0.973898</td>
          <td>1.083473</td>
          <td>0.663566</td>
        </tr>
        <tr>
          <th>2</th>
          <td>0.862783</td>
          <td>0.757669</td>
          <td>0.775862</td>
          <td>0.775123</td>
          <td>0.829735</td>
          <td>0.763393</td>
          <td>0.776532</td>
          <td>0.762319</td>
          <td>0.871343</td>
          <td>0.699622</td>
          <td>0.612026</td>
          <td>0.539308</td>
        </tr>
        <tr>
          <th>5</th>
          <td>0.379608</td>
          <td>0.555293</td>
          <td>0.368967</td>
          <td>0.470159</td>
          <td>0.378897</td>
          <td>0.410572</td>
          <td>0.589214</td>
          <td>0.434686</td>
          <td>0.395905</td>
          <td>0.419958</td>
          <td>0.461235</td>
          <td>0.473515</td>
        </tr>
        <tr>
          <th>10</th>
          <td>0.301479</td>
          <td>0.316046</td>
          <td>0.374528</td>
          <td>0.303198</td>
          <td>0.407169</td>
          <td>0.359681</td>
          <td>0.288451</td>
          <td>0.360526</td>
          <td>0.402298</td>
          <td>0.398315</td>
          <td>0.393545</td>
          <td>0.439519</td>
        </tr>
        <tr>
          <th>20</th>
          <td>0.356484</td>
          <td>0.251247</td>
          <td>0.230067</td>
          <td>0.210293</td>
          <td>0.252366</td>
          <td>0.255456</td>
          <td>0.288205</td>
          <td>0.284486</td>
          <td>0.252392</td>
          <td>0.257864</td>
          <td>0.416393</td>
          <td>0.043764</td>
        </tr>
        <tr>
          <th>50</th>
          <td>0.231620</td>
          <td>0.220888</td>
          <td>0.210009</td>
          <td>0.216061</td>
          <td>0.214163</td>
          <td>0.282138</td>
          <td>0.266862</td>
          <td>0.206823</td>
          <td>0.263674</td>
          <td>0.339590</td>
          <td>0.039424</td>
          <td>0.493669</td>
        </tr>
        <tr>
          <th>100</th>
          <td>0.394659</td>
          <td>0.189204</td>
          <td>0.256503</td>
          <td>0.206615</td>
          <td>0.214958</td>
          <td>0.218592</td>
          <td>0.240267</td>
          <td>0.225569</td>
          <td>0.243605</td>
          <td>0.314168</td>
          <td>0.412960</td>
          <td>0.406809</td>
        </tr>
        <tr>
          <th>200</th>
          <td>0.201795</td>
          <td>0.189723</td>
          <td>0.211110</td>
          <td>0.197427</td>
          <td>0.212577</td>
          <td>0.212658</td>
          <td>0.212798</td>
          <td>0.225500</td>
          <td>0.257274</td>
          <td>0.277588</td>
          <td>0.439891</td>
          <td>0.427631</td>
        </tr>
        <tr>
          <th>500</th>
          <td>0.189678</td>
          <td>0.169699</td>
          <td>0.188959</td>
          <td>0.193446</td>
          <td>0.184101</td>
          <td>0.209909</td>
          <td>0.205913</td>
          <td>0.229271</td>
          <td>0.243023</td>
          <td>0.110660</td>
          <td>0.472577</td>
          <td>0.456907</td>
        </tr>
        <tr>
          <th>1000</th>
          <td>0.181940</td>
          <td>0.183248</td>
          <td>0.183335</td>
          <td>0.186856</td>
          <td>0.191277</td>
          <td>0.195801</td>
          <td>0.197123</td>
          <td>0.209983</td>
          <td>0.262004</td>
          <td>0.184530</td>
          <td>0.471995</td>
          <td>0.467629</td>
        </tr>
        <tr>
          <th>5000</th>
          <td>0.183440</td>
          <td>0.179145</td>
          <td>0.178354</td>
          <td>0.179633</td>
          <td>0.178630</td>
          <td>0.185844</td>
          <td>0.194558</td>
          <td>0.160261</td>
          <td>0.334000</td>
          <td>NaN</td>
          <td>NaN</td>
          <td>NaN</td>
        </tr>
        <tr>
          <th>10000</th>
          <td>0.178259</td>
          <td>0.174690</td>
          <td>0.172229</td>
          <td>0.166271</td>
          <td>0.167512</td>
          <td>0.181907</td>
          <td>0.184789</td>
          <td>0.264565</td>
          <td>0.309278</td>
          <td>NaN</td>
          <td>NaN</td>
          <td>NaN</td>
        </tr>
      </tbody>
    </table>
    </div>



.. code:: ipython3

    import numpy
    import seaborn
    seaborn.heatmap(numpy.minimum(flat_piv.values, 1), cmap="YlGnBu",
                    xticklabels=list(flat_piv.index), yticklabels=list(flat_piv.columns));



.. image:: cbenchmark_vector_18_0.png