Python Package Overview
========

This section provides an overview of the Python Package from a functionality perspective. If you wish to see examples check the `Python Simple & Advanced Examples section <python-examples.html>`_ all the classes and their respective functions you can find that in the `Python Class Reference Section <python-reference.html>`_.

Below is a diagram that provides insights on the relationship between Vulkan Kompute objects and Vulkan resources, which primarily encompass ownership of either CPU and/or GPU memory.

.. image:: ../images/kompute-architecture.jpg
   :width: 70%

Package Installation 
^^^^^^^^^

Make sure you have the following dependencies installed:

* CMAKE v3.41+ (install in `Windows <https://tulip.labri.fr/TulipDrupal/?q=node/1081>`_, `Linux (Ubuntu) <https://vitux.com/how-to-install-cmake-on-ubuntu-18-04/>`_, `Mac <https://medium.com/r?url=https%3A%2F%2Fstackoverflow.com%2Fa%2F59825656%2F1889253>`_)
* Vulkan SDK installed via `official website <https://vulkan.lunarg.com/sdk/home>`_
* C++ compiler (eg. gcc for linux / mac, MSVC for Windows)

Once you set up the package dependencies, you can install Kompute from ```Pypi``` using ```pip``` by running:

.. code-block:: bash

    pip install kp

You can also install from master branch using:

.. code-block:: python

    pip install git+git://github.com/EthicalML/vulkan-kompute.git@master


Core Python Components
^^^^^^^^

The Python package exposes three main classes:

* :class:`kp.Manager` - Manages all high level Vulkan and Kompute resources created
* :class:`kp.Sequence` - Contains a set of recorded operations that can be reused
* :class:`kp.Tensor` - Core data component to manage GPU and host data used in operations

One thing that you will notice is that the class :class:`kp::OpBase` and all its relevant operator subclasses are not exposed in Python.

This is primarily because the way to interact with the operations are through the respective :class:`kp.Manager` and :class:`kp.Sequence` functions.

More specifically, it can be through the following functions:

* mgr.eval_<opname> - Runs operation under an existing named sequence
* mgr.eval_<opname>_def - Runs operation under a new anonymous sequence
* mgr.eval_async_<opname> - Runs operation asynchronously under an existing named sequence
* mgr.eval_async_<opname>_def - Runs operation asynchronously under a new anonymous sequence
* seq.record_<opname> - Records operation in sequence (requires sequence to be in recording mode)


Log Level Configuration
^^^^^^

Logging inside the C++ uses the PyBind logging, which allows for all the std::cout to be passed to a python logger.

All python output is logged to the logger with the name `kp`. You can interact with the logger similar to any python logging as per the example below:


.. code-block:: python
   :linenos:

    >>> import kp
    >>> import logging
    >>>
    >>> kp_logger = logging.getLogger("kp")
    >>> kp_logger.setLevel(logging.INFO)
    >>>
    >>> kp.Manager()
    INFO:kp:Using physical device index {} found {}
    <kp.Manager object at 0x7f2ac075ca30>

    >>> kp_logger.setLevel(logging.DEBUG)
    >>>
    >>> kp.Manager()
    DEBUG:kp:Kompute Manager creating instance
    DEBUG:kp:Kompute Manager Instance Created
    DEBUG:kp:Kompute Manager creating Device
    INFO:kp:Using physical device index {} found {}
    DEBUG:kp:Kompute Manager device created
    DEBUG:kp:Kompute Manager compute queue obtained
    DEBUG:kp:Kompute Manager Destructor started
    INFO:kp:Destroying device
    DEBUG:kp:Kompute Manager Destroyed Device
    DEBUG:kp:Kompute Manager Destroyed Instance
    <kp.Manager object at 0x7f2af6109e30>