Skip to content

Commit c5b8f13

Browse files
kennykosKennyKosIvanGrigorik
authored
Update install instructions (#317)
* Update install instructions Bring pykokkos install instructions up to date with kokkos/pykokkos-base#84 * Apply suggestion from @kennykos correct grammar for install instructions * update install instructions --------- Co-authored-by: KennyKos <{ID}+{username}@users.noreply.github.com> Co-authored-by: Ivan Grigorik <givan502@gmail.com>
1 parent 14464aa commit c5b8f13

1 file changed

Lines changed: 57 additions & 42 deletions

File tree

‎docs/installation.rst‎

Lines changed: 57 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -2,38 +2,41 @@
22
Installation
33
============
44

5-
We recommend using Docker for running applications and developing (see
6-
:ref:`Using Docker<using_docker>`, but detailed installation
7-
instructions are available (see :ref:`Native
8-
Installation<native_installation>`).
5+
We provide a Docker container for running applications and developing
6+
on Linux x86 systems with the Serial and OpenMP host execution space
7+
(see :ref:`Using Docker<using_docker>`).
8+
We provide detailed install instructions for all other
9+
operating systems and executions spaces
10+
(see :ref:`Native Installation<native_installation>`).
911

1012
.. _using_docker:
1113

1214
Using Docker
1315
------------
1416

15-
You can use the PyKokkos Docker image to develop PyKokkos itself, as
16-
well as develop and run applications. We recommend using the ``pk``
17-
script for interacting with the image and containers.
17+
Currently deprecated. Work in progress.
18+
.. You can use the PyKokkos Docker image to develop PyKokkos itself, as
19+
.. well as develop and run applications. We recommend using the ``pk``
20+
.. script for interacting with the image and containers.
1821
19-
To run an application in a container, you can execute the following
20-
command:
22+
.. To run an application in a container, you can execute the following
23+
.. command:
2124
22-
.. code-block:: bash
25+
.. .. code-block:: bash
2326
24-
./pk pk_example examples/kokkos-tutorials/workload/01.py
27+
.. ./pk pk_example examples/kokkos-tutorials/workload/01.py
2528
26-
The command above will pull the image from the Docker Hub, run a
27-
container, include this repository as a volume, and run the example
28-
application from the given path.
29+
.. The command above will pull the image from the Docker Hub, run a
30+
.. container, include this repository as a volume, and run the example
31+
.. application from the given path.
2932
30-
If you would like to run another example application, you can simply
31-
change the path (the last argument in the command above).
33+
.. If you would like to run another example application, you can simply
34+
.. change the path (the last argument in the command above).
3235
33-
Note that code you are running should be in the PyKokkos repository.
34-
If you would like to run from another directory you will need to
35-
include the directory as a volume; take a look at the ``pk`` script in
36-
that case.
36+
.. Note that code you are running should be in the PyKokkos repository.
37+
.. If you would like to run from another directory you will need to
38+
.. include the directory as a volume; take a look at the ``pk`` script in
39+
.. that case.
3740
3841
Design Decision
3942
^^^^^^^^^^^^^^^
@@ -61,43 +64,52 @@ already included in the image), you would need to install it
6164
Native Installation
6265
-------------------
6366

64-
Clone `pykokkos-base <https://github.com/kokkos/pykokkos-base>`_ and
67+
Clone `pykokkos <https://github.com/kokkos/pykokkos>`_ and
6568
create a conda environment:
6669

6770
.. code-block:: bash
6871
69-
git clone https://github.com/kokkos/pykokkos-base.git
70-
cd pykokkos-base/
71-
conda create --name pyk --file requirements.txt python=3.11
72+
git clone https://github.com/kokkos/pykokkos.git
73+
cd pykokkos/
74+
conda create --name pyk --file base/requirements.txt python=3.13
7275
conda activate pyk
7376
7477
Once the necessary packages have been downloaded and installed,
75-
install ``pykokkos-base`` with CUDA and OpenMP enabled:
78+
install ``base`` with required CMake flags (example performs an install with OpenMP and CUDA enabled):
7679

7780
.. code-block:: bash
78-
79-
python setup.py install -- -DENABLE_LAYOUTS=ON -DENABLE_MEMORY_TRAITS=OFF -DENABLE_VIEW_RANKS=3 -DENABLE_CUDA=ON -DENABLE_THREADS=OFF -DENABLE_OPENMP=ON
80-
81-
Other ``pykokkos-base`` configuration and installation options can be
81+
PYKOKKOS_BASE_SETUP_ARGS="\
82+
-DKokkos_ENABLE_THREADS=OFF \ # trigger pthreads execution space
83+
-DKokkos_ENABLE_OPENMP=ON \ # trigger openmp execution space
84+
-DENABLE_CUDA=ON \ # trigger cuda execution space
85+
-DENABLE_HIP=OFF \ # trigger hip execution space
86+
-DENABLE_LAYOUTS=ON \ # trigger layout left/right ordering
87+
-DENABLE_MEMORY_TRAITS=OFF \ # trigger memory space concept
88+
-DENABLE_VIEW_RANKS=3 \ # maximum number of view ranks enabled
89+
" \
90+
python install_base.py install
91+
See `Kokkos CMake Options <https://kokkos.org/kokkos-kernels/docs/cmake-keywords.html>`_ for a complete list of CMake flags.
92+
Other ``pykokkos`` configuration and installation options can be
8293
found in that project's `README
83-
<https://github.com/kokkos/pykokkos-base/blob/main/README.md>`_. Note
94+
<https://github.com/kokkos/pykokkos/blob/main/base/README.md>`_. Note
8495
that this step will compile a large number of bindings which can take
85-
a while to complete. Please open an issue if you run into any problems
86-
with ``pykokkos-base``.
96+
a while to complete.
8797

88-
Once ``pykokkos-base`` has been installed, clone ``pykokkos`` and
89-
install its requirements:
98+
.. note::
99+
Please open an issue
100+
or reach out in the `Kokkos slack <https://kokkos.org/community/chat/>`_
101+
**#pykokkos** channel
102+
if you run into any problems
103+
with ``base``.
90104

91-
.. code-block:: bash
105+
Once ``base`` has been installed, you can install ``pykokkos`` itself:
92106

93-
cd ..
94-
git clone https://github.com/kokkos/pykokkos.git
95-
cd pykokkos/
107+
.. code-block:: bash
96108
conda install -c conda-forge pybind11 cupy patchelf
97109
pip install --user -e .
98110
99111
Note that ``cupy`` is only required if CUDA is enabled in
100-
pykokkos-base. In some cases, this might result in a ``cupy`` import
112+
base. In some cases, this might result in a ``cupy`` import
101113
error inside ``pykokkos`` similar to the following:
102114

103115
.. code-block::
@@ -110,7 +122,7 @@ error inside ``pykokkos`` similar to the following:
110122
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)
111123
112124
This is due to a mismatch in ``libstdc++.so`` versions between the
113-
system library which ``pykokkos-base`` depends on and the library in
125+
system library which ``base`` depends on and the library in
114126
the conda environment which ``cupy`` depends on. This can be solved by
115127
setting the ``LD_PRELOAD`` environment variable to force loading of
116128
the correct library like so:
@@ -128,8 +140,11 @@ To verify that ``pykokkos`` has been installed correctly, install
128140
python runtests.py
129141
130142
.. note::
131-
132-
Please open an issue for help with installation.
143+
Please open an issue
144+
or reach out in the `Kokkos slack <https://kokkos.org/community/chat/>`_
145+
**#pykokkos** channel
146+
if you run into any problems
147+
with ``pykokkos``.
133148

134149
.. toctree::
135150
:maxdepth: 2

0 commit comments

Comments
 (0)