deploy: bed9349

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 6fcb35d8e5bb339718a9b13d1ae86e56
+tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/concepts.rst.txt

@@ -0,0 +1,57 @@
+
+Concepts
+========
+
+On this page, we introduce the key PyKokkos concepts.  We will use the
+following example to illustrate the key concepts.
+
+.. code-block:: python
+
+   import pykokkos as pk
+
+   @pk.workunit
+   def hello(i: int):
+       pk.printf("Hello, World! from i = %d\n", i)
+    
+   def main():
+       pk.parallel_for(10, hello)
+    
+   main()
+
+* **Pattern** specifies the structure of computation (e.g.,
+  ``parallel_for``)
+* **Policy** specifies the way computations are executed (e.g., ``10``
+  parallel units of work)
+* **Work Unit** is a function that performs each unit of work (e.g.,
+  ``hello``)
+
+Execution of a Pattern creates `work`. In the example above, there
+will be 10 `units of work`, such that each unit executes the ``hello``
+function. `Index`, which is the first argument of the Work Unit,
+identifies a unique unit of work. PyKokkos maps work to execution
+resources.
+
+.. note::
+
+   Ordering of execution of units of work is not guaranteed by the
+   runtime.
+
+The three key concepts are closely intertwined.
+
+Kokkos
+------
+
+.. note::
+
+   This section might be of interest only to those familiar with Kokkos.
+
+Unlike in Kokkos, we do not use the term "Computational Body" (but
+rather "Work Unit"), because code for any work is always in a separate
+function. Due to the limitation of Python lambdas, there are no
+multiple ways like in `Kokkos
+<https://kokkos.github.io/kokkos-core-wiki/ProgrammingGuide/ParallelDispatch.html#should-i-use-a-functor-or-a-lambda>`_
+to write computational bodies.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:

_sources/examples.rst.txt

@@ -0,0 +1,50 @@
+
+Examples
+========
+
+There are a number of `examples
+<https://github.com/kokkos/pykokkos/tree/main/examples>`_ in the
+PyKokkos repository. The table below shows some representative cases
+that demonstrate various features.
+
+.. list-table:: Examples
+   :widths: 25 25 50
+   :header-rows: 1
+
+   * - Example
+     - PyKokkos
+     - Kokkos
+   * - parallel_reduce
+     - `PyKokkos <https://github.com/kokkos/pykokkos/blob/main/examples/kokkos-tutorials/standalone/02.py>`__
+     - `Kokkos <https://github.com/kokkos/kokkos-tutorials/blob/main/Exercises/02/Solution/exercise_2_solution.cpp>`__
+   * - Cuda
+     - `PyKokkos <https://github.com/kokkos/pykokkos/blob/main/examples/kokkos-tutorials/standalone/04.py>`__
+     - `Kokkos <https://github.com/kokkos/kokkos-tutorials/blob/main/Exercises/04/Solution/exercise_4_solution.cpp>`__
+   * - team_policy
+     - `PyKokkos <https://github.com/kokkos/pykokkos/blob/main/examples/kokkos-tutorials/standalone/team_policy.py>`__
+     - `Kokkos <https://github.com/kokkos/kokkos-tutorials/blob/main/Exercises/team_policy/Solution/team_policy_solution.cpp>`__
+   * - team_vector_loop
+     - `PyKokkos <https://github.com/kokkos/pykokkos/blob/main/examples/kokkos-tutorials/standalone/team_vector_loop.py>`__
+     - `Kokkos <https://github.com/kokkos/kokkos-tutorials/blob/main/Exercises/team_vector_loop/Solution/team_vector_loop_solution.cpp>`__
+   * - subview
+     - `PyKokkos <https://github.com/kokkos/pykokkos/blob/main/examples/kokkos-tutorials/standalone/subview.py>`__
+     - `Kokkos <https://github.com/kokkos/kokkos-tutorials/blob/main/Exercises/subview/Solution/exercise_subview_solution.cpp>`__
+   * - mdrange
+     - `PyKokkos <https://github.com/kokkos/pykokkos/blob/main/examples/kokkos-tutorials/workload/mdrange.py>`__
+     - `Kokkos <https://github.com/kokkos/kokkos-tutorials/blob/main/Exercises/mdrange/Solution/exercise_mdrange_solution.cpp>`__
+   * - nstream
+     - `PyKokkos <https://github.com/kokkos/pykokkos/blob/main/examples/ParRes/workload/nstream.py>`__
+     - `Kokkos <https://github.com/ParRes/Kernels/blob/default/Cxx11/nstream-kokkos.cc>`__
+   * - stencil
+     - `PyKokkos <https://github.com/kokkos/pykokkos/blob/main/examples/ParRes/workload/stencil.py>`__
+     - `Kokkos <https://github.com/ParRes/Kernels/blob/default/Cxx11/stencil-kokkos.cc>`__
+   * - transpose
+     - `PyKokkos <https://github.com/kokkos/pykokkos/blob/main/examples/ParRes/workload/transpose.py>`__
+     - `Kokkos <https://github.com/ParRes/Kernels/blob/default/Cxx11/transpose-kokkos.cc>`__
+   * - ExaMiniMD
+     - `PyKokkos <https://github.com/kokkos/pykokkos/tree/main/examples/ExaMiniMD>`__
+     - `Kokkos <https://github.com/ECP-copa/ExaMiniMD>`__
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:

_sources/index.rst.txt

@@ -0,0 +1,63 @@
+
+PyKokkos Documentation
+========================
+
+PyKokkos is a framework for writing high-performance Python code
+similar to Numba. In contrast to Numba, PyKokkos kernels are primarily
+parallel and are also performance portable, meaning that they can run
+efficiently on different hardware (CPUs, NVIDIA GPUs, and AMD GPUs)
+with no changes required.
+
+PyKokkos is open source and available on `GitHub
+<https://github.com/kokkos/pykokkos>`_.
+
+Below is a quick example that uses PyKokkos.
+
+.. code-block:: python
+
+   import pykokkos as pk
+
+   @pk.workunit
+   def hello(i: int):
+       pk.printf("Hello, World! from i = %d\n", i)
+
+   def main():
+       pk.parallel_for(10, hello)
+
+   main()
+
+Kokkos
+------
+
+In the background, PyKokkos translates kernels designated by the user
+into C++ `Kokkos <https://github.com/kokkos/kokkos>`_ and
+automatically generates language bindings to run the generated code.
+
+.. note::
+
+   Knowing Kokkos is not necessary for using PyKokkos.
+
+On some pages of this documentation, as appropriate, we will have a
+section `Kokkos` to discuss similarities between Kokkos and
+PyKokkos. We believe that the `Kokkos` section will be primarily of
+interest to those already familiar with the Kokkos framework.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   installation
+   concepts
+   patterns
+   policies
+   workunits
+   ndarrays
+   examples
+
+..
+    Indices and tables
+    ==================
+
+    * :ref:`genindex`
+    * :ref:`modindex`
+    * :ref:`search`

_sources/installation.rst.txt

@@ -0,0 +1,136 @@
+
+Installation
+============
+
+We recommend using Docker for running applications and developing (see
+:ref:`Using Docker<using_docker>`, but detailed installation
+instructions are available (see :ref:`Native
+Installation<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.
+
+To run an application in a container, you can execute the following
+command:
+
+.. code-block:: bash
+
+   ./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.
+
+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.
+
+Design Decision
+^^^^^^^^^^^^^^^
+
+At the moment, we decided to include the PyKokkos repository as a
+volume when starting a container, which enables the development
+workflow. Namely, the ``pk`` script will include the current local
+version of this repository, which means that any local modifications
+(e.g., a change in ``parallel_dispatch.py``) will be used in the
+subsequent runs of the ``pk`` script. In the future, we might separate
+user and development workflows.
+
+Limitations
+^^^^^^^^^^^
+
+One, as described above, you would need to modify the ``pk`` script if
+you are running code that is not part of this repository.
+
+Two, if your code requires dependencies (e.g., python libraries not
+already included in the image), you would need to install it
+(temporarily) in the container or build your own image.
+
+.. _native_installation:
+
+Native Installation
+-------------------
+
+Clone `pykokkos-base <https://github.com/kokkos/pykokkos-base>`_ 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
+   conda activate pyk
+
+Once the necessary packages have been downloaded and installed,
+install ``pykokkos-base`` with CUDA and OpenMP 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
+found in that project's `README
+<https://github.com/kokkos/pykokkos-base/blob/main/README.md>`_.  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``.
+
+Once ``pykokkos-base`` has been installed, clone ``pykokkos`` and
+install its requirements:
+
+.. code-block:: bash
+
+   cd ..
+   git clone https://github.com/kokkos/pykokkos.git
+   cd pykokkos/
+   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
+error inside ``pykokkos`` similar to the following:
+
+.. code-block::
+
+   ImportError:
+   ================================================================
+   Failed to import CuPy.
+
+   Original error:
+   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
+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:
+
+.. code-block:: bash
+
+   export LD_PRELOAD=/PATH/TO/ENV/lib/libstdc++.so.6
+
+To verify that ``pykokkos`` has been installed correctly, install
+``pytest`` and run the tests:
+
+.. code-block:: bash
+
+   conda install pytest
+   python runtests.py
+
+.. note::
+
+  Please open an issue for help with installation.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents: