Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Initialization.rst: fix superscripts and render code as code #531

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Initialization.rst: fix superscripts and render code as code #531

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6eed4b9
Initialization.rst: fix superscripts and render code as code
RL-S Jun 7, 2024
8c436a0
Merge branch 'main' into patch-1
crtrott Jul 2, 2024
2ce6439
Initialization.rst: response to ajpowelsnl
RL-S Jul 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 21 additions & 16 deletions docs/source/ProgrammingGuide/Initialization.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,40 +49,42 @@ Kokkos chooses the two spaces using the following list:
8. `Kokkos::Threads`
9. `Kokkos::Serial`

The highest execution space in the list that is enabled is Kokkos' default execution space, and the highest enabled host execution space is Kokkos' default host execution space. For example, if `Kokkos::Cuda`, `Kokkos::OpenMP`, and `Kokkos::Serial` are enabled, then `Kokkos::Cuda` is the default execution space and `Kokkos::OpenMP` is the default host execution space.:sup:`1` In cases where the highest enabled backend is a host parallel execution space the `DefaultExecutionSpace` and the `DefaultHostExecutionSpace` will be the same.
The highest execution space in the list that is enabled is Kokkos' default execution space, and the highest enabled host execution space is Kokkos' default host execution space. For example, if `Kokkos::Cuda`, `Kokkos::OpenMP`, and `Kokkos::Serial` are enabled, then `Kokkos::Cuda` is the default execution space and `Kokkos::OpenMP` is the default host execution space\ :sup:`1`. In cases where the highest enabled backend is a host parallel execution space the `DefaultExecutionSpace` and the `DefaultHostExecutionSpace` will be the same.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just out of curiosity, is the "highest" execution space formally a Kokkos convention, something approximating operator precedence, or is it a concept we just expect everyone to understand automatically? If it's not been formalized, perhaps a sentence or two defining it might be useful ...?


`Kokkos::initialize <../API/Initialize-and-Finalize.html#kokos-initialize>`_ parses the command line for flags prefixed with `--kokkos-`, and removes all recognized flags. Argument options are given with an equals (`=`) sign. If the same argument occurs more than once, the last one is used. For example, the arguments

--kokkos-threads=4 --kokkos-threads=3

set the number of threads to 3. Table 5.1 gives a full list of command-line options.
set the number of threads to 3. `Table 5.1 <Table_cli-opts>`_ gives a full list of command-line options.

.. Table_cli-opts:

Table 5.1: Command-line options for Kokkos::initialize

.. list-table::

* - Argument
- Description
* - --kokkos-help --help
* - :code:`--kokkos-help`
- print this message
* - --kokkos-disable-warnings
* - :code:`--kokkos-disable-warnings`
- disable kokkos warning messages
* - --kokkos-print-configuration
* - :code:`--kokkos-print-configuration`
- print configuration
* - --kokkos-tune-internals
* - :code:`--kokkos-tune-internals`
- allow Kokkos to autotune policies and declare tuning features through the tuning system. If left off, Kokkos uses heuristics.
* - --kokkos-num-threads=INT
* - :code:`--kokkos-num-threads=INT`
- specify total number of threads to use for parallel regions on the host
* - --kokkos-device-id=INT
* - :code"`--kokkos-device-id=INT`
- specify device id to be used by Kokkos
* - --kokkos-map-device-id-by=(random\|mpi_rank), default: mpi_rank
- strategy to select device-id automatically from available devices: random or mpi_rank:sup:`2`
* - --kokkos-tools-libs=STR
* - :code:`--kokkos-map-device-id-by=(random\|mpi_rank)`, default: :code:`mpi_rank`
- strategy to select device-id automatically from available devices: random or mpi_rank\ :sup:`2`
* - :code:`--kokkos-tools-libs=STR`
- specify which of the tools to use. Must either be full path to library or name of library if the path is present in the runtime library search path (e.g. LD_LIBRARY_PATH)
* - --kokkos-tools-help
* - :code:`--kokkos-tools-help`
- query the (loaded) kokkos-tool for its command-line option support (which should then be passed via --kokkos-tools-args="...")
* - --kokkos-tools-args=STR
- a single (quoted) string of options which will be whitespace delimited and passed to the loaded kokkos-tool as command-line arguments. E.g. `<EXE> --kokkos-tools-args="-c input.txt"` will pass `<EXE> -c input.txt` as argc/argv to tool
* - :code:`--kokkos-tools-args=STR`
- a single (quoted) string of options which will be whitespace delimited and passed to the loaded kokkos-tool as command-line arguments. E.g. :code:`<EXE> --kokkos-tools-args="-c input.txt"` will pass :code:`<EXE> -c input.txt` as argc/argv to tool

When passing a boolean as a string, the acceptable values are:
- true, yes, 1
Expand All @@ -100,14 +102,17 @@ The values are case insensitive.
5.2 Initialization by environment variable
------------------------------------------

Instead of using command-line arguments, one may use environment variables. The environment variables are identical to the arguments in Table 5.1 but they are upper case and the dash is replaced by an underscore. For example, if we want to set the number of threads to 3, we have
Instead of using command-line arguments, one may use environment variables. The environment variables are identical to the arguments in `Table 5.1 <Table_cli-opts>`_ but they are upper case and the dash is replaced by an underscore. For example, if we want to set the number of threads to 3, we may use

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would you please link to table 5.1?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

By link, I meant a URL one can click for additional information. Is "< Table clio-pts>" a clickable URL?

Copy link
Contributor Author

@RL-S RL-S Jul 16, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's supposed to be one, yes. You click it, and it jumps to Table 5.1. For that, I put an anchor above it, in line 60:
.. Table_cli-opts:
I'm not an expert in reStructured text, and neither is GitHub's preview, so references are a bit iffy. But the syntax
`Table 5.1 <Table_cli-opts>`_
is supposed to display 'Table 5.1' and the reference target is what's within the angle braces (< >). The underscore at the end is necessary, but I don't know, why.

.. code-block:: sh

KOKKOS_NUM_THREADS=3


5.3 Initialization by struct
----------------------------

Instead of giving `Kokkos::initialize() <../API/core/initialize_finalize/initialize.html>`_ command-line arguments, one may directly pass in initialization parameters using the `Kokkos::InitializationSettings` struct. If one wants to set a options using the struct, one can use the set functions `set_xxx` where `xxx` is the identical to the arguments in Table 5.1 where the dash has been replaced by an underscore. To check if a variable has been set, one can use the `has_xxx` functions. Finally, to get the value that was set, one can use the `get_xxx` functions.
Instead of giving `Kokkos::initialize() <../API/core/initialize_finalize/initialize.html>`_ command-line arguments, one may directly pass in initialization parameters using the `Kokkos::InitializationSettings` struct. If one wants to set options using the struct, one can use the functions `set_xxx` where `xxx` is identical to the arguments in `Table 5.1 <Table_cli-opts>`_ where the dash has been replaced by an underscore. To check if a variable has been set, one can use the `has_xxx` functions. Finally, to get the value that was set, one can use the `get_xxx` functions.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there API documentation on using the struct for initialization settings? If not, that might be something to do, comparing one method to the other. I have the same question as above about the link to Table 5.1.



If you do not set `num_threads`, Kokkos will try to determine a default value if possible or otherwise set it to 1. In particular, Kokkos can use the `hwloc` library to determine default settings using the assumption that the process binding mask is unique, i.e., that this process does not share any cores with another process. Note that the default value of each parameter is -1.
Expand Down
Loading