Add changes for 061da8c

Author: actions-user

_sources/guides.rst.txt

@@ -0,0 +1,8 @@
+Guides
+=============
+.. toctree::
+   :maxdepth: 1
+
+   guides/introduction.rst
+   guides/promotion.rst
+   guides/prelude.rst

_sources/guides/introduction.md.txt

@@ -0,0 +1,56 @@
+Getting started
+===============
+
+Kernel Float is a header-only library that makes it easy to work with vector types and low-precision floating-point types, mainly focusing on CUDA kernel code.
+
+Installation
+------------
+
+The easiest way to use the library is get the single header file from github:
+
+```bash
+wget https://raw.githubusercontent.com/KernelTuner/kernel_float/main/single_include/kernel_float.h
+```
+
+Next, include this file into your program.
+It is conventient to define a namespace alias `kf` to shorten the full name `kernel_float`.
+
+
+```C++
+#include "kernel_float.h"
+namespace kf = kernel_float;
+```
+
+
+Example C++ code
+----------------
+
+Kernel Float essentially offers a single data-type `kernel_float::vec<T, N>` that stores `N` elements of type `T`.
+This type can be initialized normally using list-initialization (e.g., `{a, b, c}`) and elements can be accessed using the `[]` operator.
+Operation overload is available to perform binary operations (such as `+`, `*`, and `&`), where the optimal intrinsic for the available types is selected automatically.
+
+Many mathetical functions (like `log`, `sin`, `cos`) are also available, see the [API reference](../api) for the full list of functions.
+In some cases, certain operations might not be natively supported by the platform for the some floating-point type.
+In these cases, Kernel Float falls back to performing the operations in 32 bit precision.
+
+The code below shows a very simple example of how to use Kernel Float:
+
+```C++
+#include "kernel_float.h"
+namespace kf = kernel_float;
+
+int main() {
+  using Type = float;
+  const int N = 8;
+
+  kf::vec<int, N> i = kf::range<int, N>();
+  kf::vec<Type, N> x = kf::cast<Type>(i);
+  kf::vec<Type, N> y = x * kf::sin(x);
+  Type result = kf::sum(y);
+  printf("result=%f", double(result));
+
+  return EXIT_SUCCESS;
+}
+```
+
+Notice how easy it would be to change the floating-point type `Type` or the vector length `N` without affecting the rest of the code.

_sources/guides/prelude.md.txt

@@ -0,0 +1,42 @@
+Using `kernel_float::prelude`
+===
+
+When working with Kernel Float, you'll find that you need to prefix every function and type with the `kernel_float::...` prefix. 
+This can be a bit cumbersome. 
+It's strongly discouraged not to dump the entire `kernel_float` namespace into the global namespace (with `using namespace kernel_float`) since
+many symbols in Kernel Float may clash with global symbols, causing conflicts and issues.
+
+To work around this, the library provides a handy `kernel_float::prelude` namespace. This namespace contains a variety of useful type and function aliases that won't conflict with global symbols.
+
+To make use of it, use the following code:
+
+
+```C++
+#include "kernel_float.h"
+using namespace kernel_float::prelude;
+
+// You can now use aliases like `kf`, `kvec`, `kint`, etc.
+```
+
+The prelude defines many aliases, include the following:
+
+| Prelude name | Full name |
+|---|---|
+| `kf` | `kernel_float` |
+| `kvec<T, N>`  | `kernel_float::vec<T, N>`  |
+| `into_kvec(v)`  | `kernel_float::into_vec(v)`  |
+| `make_kvec(a, b, ...)`  | `kernel_float::make_vec(a, b, ...)`  |
+| `kvec2<T>`, `kvec3<T>`, ...  | `kernel_float::vec<T, 2>`, `kernel_float::vec<T, 3>`, ...  |
+| `kint<N>` | `kernel_float::vec<int, N>` |
+| `kint2`, `kint3`, ...  | `kernel_float::vec<int, 2>`, `kernel_float::vec<int, 3>`, ...  |
+| `klong<N>` | `kernel_float::vec<long, N>` |
+| `klong2`, `klong3`, ...  | `kernel_float::vec<long, 2>`, `kernel_float::vec<long, 3>`, ...  |
+| `kbfloat16x<N>` | `kernel_float::vec<bfloat16, N>` |
+| `kbfloat16x2`, `kbfloat16x3`, ...  | `kernel_float::vec<bfloat16, 2>`, `kernel_float::vec<bfloat16, 3>`, ...  |
+| `khalf<N>` | `kernel_half::vec<half, N>` |
+| `khalf2`, `khalf3`, ...  | `kernel_half::vec<half, 2>`, `kernel_half::vec<half, 3>`, ...  |
+| `kfloat<N>` | `kernel_float::vec<float, N>` |
+| `kfloat2`, `kfloat3`, ...  | `kernel_float::vec<float, 2>`, `kernel_float::vec<float, 3>`, ...  |
+| `kdouble<N>` | `kernel_float::vec<double, N>` |
+| `kdouble2`, `kdouble3`, ...  | `kernel_float::vec<double, 2>`, `kernel_float::vec<double, 3>`, ...  |
+| ... | ... |

_sources/guides/promotion.rst.txt

@@ -0,0 +1,34 @@
+Type Promotion
+==============
+
+For operations that involve two input arguments (or more), ``kernel_float`` will first convert the inputs into a common type before applying the operation.
+For example, when adding ``vec<int, N>`` to a ``vec<float, N>``, both arguments must first be converted into a ``vec<float, N>``.
+
+This procedure is called "type promotion" and is implemented as follows.
+First, all arguments are converted into a vector by calling ``into_vec``.
+Next, all arguments must have length ``N`` or length ``1`` and vectors of length ``1`` are resized to become length ``N``.
+Finally, the vector element types are promoted into a common type.
+
+The rules for element type promotion in ``kernel_float`` are slightly different than in regular C++.
+In short, for two element types ``T`` and ``U``, the promotion rules can be summarized as follows:
+
+* If one of the types is ``bool``, the result is the other type.
+* If one type is a floating-point type and the other is a signed or unsigned integer, the result is the floating-point type.
+* If both types are floating-point types, the result is the largest of the two types. An exception here is combining ``half`` and ``bfloat16``, which results in ``float``.
+* If both types are integer types of the same signedness, the result is the largest of the two types.
+* Combining a signed integer and unsigned integer type is not allowed.
+
+Overview
+--------
+
+The type promotion rules are shown in the table below.
+The labels are as follows:
+
+* ``b``: boolean
+* ``iN``: signed integer of ``N`` bits (e.g., ``int``, ``long``)
+* ``uN``: unsigned integer of ``N`` bits (e.g., ``unsigned int``, ``size_t``)
+* ``fN``: floating-point type of ``N`` bits (e.g., ``float``, ``double``)
+* ``bf16``: bfloat16 floating-point format.
+
+.. csv-table:: Type Promotion Rules.
+   :file: promotion_table.csv

_sources/index.rst.txt

@@ -4,18 +4,20 @@
    :caption: Contents
 
    Kernel Float <self>
+   guides
    api
    license
    Github repository <https://github.com/KernelTuner/kernel_float>
 
 
-.. mdinclude:: ../README.md
+.. include:: ../README.md
+   :parser: myst_parser.sphinx_
 
 
 
 
 Indices and tables
-============
+==================
 
 * :ref:`genindex`
 * :ref:`modindex`

api.html

@@ -20,7 +20,7 @@
     <link rel="index" title="Index" href="genindex.html" />
     <link rel="search" title="Search" href="search.html" />
     <link rel="next" title="Types" href="api/types.html" />
-    <link rel="prev" title="Kernel Float" href="index.html" /> 
+    <link rel="prev" title="Using kernel_float::prelude" href="guides/prelude.html" /> 
 </head>
 
 <body class="wy-body-for-nav"> 
@@ -45,6 +45,7 @@
               <p class="caption" role="heading"><span class="caption-text">Contents</span></p>
 <ul class="current">
 <li class="toctree-l1"><a class="reference internal" href="index.html">Kernel Float</a></li>
+<li class="toctree-l1"><a class="reference internal" href="guides.html">Guides</a></li>
 <li class="toctree-l1 current"><a class="current reference internal" href="#">API Reference</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="api/types.html">Types</a></li>
 <li class="toctree-l2"><a class="reference internal" href="api/primitives.html">Primitives</a></li>
@@ -220,7 +221,7 @@ <h1>API Reference<a class="headerlink" href="#api-reference" title="Permalink to
            </div>
           </div>
           <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
-        <a href="index.html" class="btn btn-neutral float-left" title="Kernel Float" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
+        <a href="guides/prelude.html" class="btn btn-neutral float-left" title="Using kernel_float::prelude" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
         <a href="api/types.html" class="btn btn-neutral float-right" title="Types" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
     </div>
 

api/binary_operators.html

@@ -45,6 +45,7 @@
               <p class="caption" role="heading"><span class="caption-text">Contents</span></p>
 <ul class="current">
 <li class="toctree-l1"><a class="reference internal" href="../index.html">Kernel Float</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../guides.html">Guides</a></li>
 <li class="toctree-l1 current"><a class="reference internal" href="../api.html">API Reference</a><ul class="current">
 <li class="toctree-l2"><a class="reference internal" href="types.html">Types</a></li>
 <li class="toctree-l2"><a class="reference internal" href="primitives.html">Primitives</a></li>

api/conditional.html

@@ -45,6 +45,7 @@
               <p class="caption" role="heading"><span class="caption-text">Contents</span></p>
 <ul class="current">
 <li class="toctree-l1"><a class="reference internal" href="../index.html">Kernel Float</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../guides.html">Guides</a></li>
 <li class="toctree-l1 current"><a class="reference internal" href="../api.html">API Reference</a><ul class="current">
 <li class="toctree-l2"><a class="reference internal" href="types.html">Types</a></li>
 <li class="toctree-l2"><a class="reference internal" href="primitives.html">Primitives</a></li>

api/generation.html

@@ -45,6 +45,7 @@
               <p class="caption" role="heading"><span class="caption-text">Contents</span></p>
 <ul class="current">
 <li class="toctree-l1"><a class="reference internal" href="../index.html">Kernel Float</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../guides.html">Guides</a></li>
 <li class="toctree-l1 current"><a class="reference internal" href="../api.html">API Reference</a><ul class="current">
 <li class="toctree-l2"><a class="reference internal" href="types.html">Types</a></li>
 <li class="toctree-l2"><a class="reference internal" href="primitives.html">Primitives</a></li>

api/mathematical.html

@@ -45,6 +45,7 @@
               <p class="caption" role="heading"><span class="caption-text">Contents</span></p>
 <ul class="current">
 <li class="toctree-l1"><a class="reference internal" href="../index.html">Kernel Float</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../guides.html">Guides</a></li>
 <li class="toctree-l1 current"><a class="reference internal" href="../api.html">API Reference</a><ul class="current">
 <li class="toctree-l2"><a class="reference internal" href="types.html">Types</a></li>
 <li class="toctree-l2"><a class="reference internal" href="primitives.html">Primitives</a></li>