diff --git a/docs/installation.rst b/docs/installation.rst index 17e6c9fb..9a130d5f 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -2,38 +2,41 @@ Installation ============ -We recommend using Docker for running applications and developing (see -:ref:`Using Docker`, but detailed installation -instructions are available (see :ref:`Native -Installation`). +We provide a Docker container for running applications and developing +on Linux x86 systems with the Serial and OpenMP host execution space +(see :ref:`Using Docker`). +We provide detailed install instructions for all other +operating systems and executions spaces +(see :ref:`Native Installation`). .. _using_docker: Using Docker ------------ -You can use the PyKokkos Docker image to develop PyKokkos itself, as -well as develop and run applications. We recommend using the ``pk`` -script for interacting with the image and containers. +Currently deprecated. Work in progress. +.. You can use the PyKokkos Docker image to develop PyKokkos itself, as +.. well as develop and run applications. We recommend using the ``pk`` +.. script for interacting with the image and containers. -To run an application in a container, you can execute the following -command: +.. To run an application in a container, you can execute the following +.. command: -.. code-block:: bash +.. .. code-block:: bash - ./pk pk_example examples/kokkos-tutorials/workload/01.py +.. ./pk pk_example examples/kokkos-tutorials/workload/01.py -The command above will pull the image from the Docker Hub, run a -container, include this repository as a volume, and run the example -application from the given path. +.. The command above will pull the image from the Docker Hub, run a +.. container, include this repository as a volume, and run the example +.. application from the given path. -If you would like to run another example application, you can simply -change the path (the last argument in the command above). +.. If you would like to run another example application, you can simply +.. change the path (the last argument in the command above). -Note that code you are running should be in the PyKokkos repository. -If you would like to run from another directory you will need to -include the directory as a volume; take a look at the ``pk`` script in -that case. +.. Note that code you are running should be in the PyKokkos repository. +.. If you would like to run from another directory you will need to +.. include the directory as a volume; take a look at the ``pk`` script in +.. that case. Design Decision ^^^^^^^^^^^^^^^ @@ -61,43 +64,52 @@ already included in the image), you would need to install it Native Installation ------------------- -Clone `pykokkos-base `_ and +Clone `pykokkos `_ and create a conda environment: .. code-block:: bash - git clone https://github.com/kokkos/pykokkos-base.git - cd pykokkos-base/ - conda create --name pyk --file requirements.txt python=3.11 + git clone https://github.com/kokkos/pykokkos.git + cd pykokkos/ + conda create --name pyk --file base/requirements.txt python=3.13 conda activate pyk Once the necessary packages have been downloaded and installed, -install ``pykokkos-base`` with CUDA and OpenMP enabled: +install ``base`` with required CMake flags (example performs an install with OpenMP and CUDA enabled): .. code-block:: bash - - python setup.py install -- -DENABLE_LAYOUTS=ON -DENABLE_MEMORY_TRAITS=OFF -DENABLE_VIEW_RANKS=3 -DENABLE_CUDA=ON -DENABLE_THREADS=OFF -DENABLE_OPENMP=ON - -Other ``pykokkos-base`` configuration and installation options can be + PYKOKKOS_BASE_SETUP_ARGS="\ + -DKokkos_ENABLE_THREADS=OFF \ # trigger pthreads execution space + -DKokkos_ENABLE_OPENMP=ON \ # trigger openmp execution space + -DENABLE_CUDA=ON \ # trigger cuda execution space + -DENABLE_HIP=OFF \ # trigger hip execution space + -DENABLE_LAYOUTS=ON \ # trigger layout left/right ordering + -DENABLE_MEMORY_TRAITS=OFF \ # trigger memory space concept + -DENABLE_VIEW_RANKS=3 \ # maximum number of view ranks enabled + " \ + python install_base.py install +See `Kokkos CMake Options `_ for a complete list of CMake flags. +Other ``pykokkos`` configuration and installation options can be found in that project's `README -`_. Note +`_. Note that this step will compile a large number of bindings which can take -a while to complete. Please open an issue if you run into any problems -with ``pykokkos-base``. +a while to complete. -Once ``pykokkos-base`` has been installed, clone ``pykokkos`` and -install its requirements: +.. note:: + Please open an issue + or reach out in the `Kokkos slack `_ + **#pykokkos** channel + if you run into any problems + with ``base``. -.. code-block:: bash +Once ``base`` has been installed, you can install ``pykokkos`` itself: - cd .. - git clone https://github.com/kokkos/pykokkos.git - cd pykokkos/ +.. code-block:: bash conda install -c conda-forge pybind11 cupy patchelf pip install --user -e . Note that ``cupy`` is only required if CUDA is enabled in -pykokkos-base. In some cases, this might result in a ``cupy`` import +base. In some cases, this might result in a ``cupy`` import error inside ``pykokkos`` similar to the following: .. code-block:: @@ -110,7 +122,7 @@ error inside ``pykokkos`` similar to the following: ImportError: /lib/x86_64-linux-gnu/libstdc++.so.6: version `GLIBCXX_3.4.29' not found (required by /PATH/TO/ENV/lib/python3.11/site-packages/cupy/_core/core.cpython-311-x86_64-linux-gnu.so) This is due to a mismatch in ``libstdc++.so`` versions between the -system library which ``pykokkos-base`` depends on and the library in +system library which ``base`` depends on and the library in the conda environment which ``cupy`` depends on. This can be solved by setting the ``LD_PRELOAD`` environment variable to force loading of the correct library like so: @@ -128,8 +140,11 @@ To verify that ``pykokkos`` has been installed correctly, install python runtests.py .. note:: - - Please open an issue for help with installation. + Please open an issue + or reach out in the `Kokkos slack `_ + **#pykokkos** channel + if you run into any problems + with ``pykokkos``. .. toctree:: :maxdepth: 2