GithubHelp home page GithubHelp logo

kokkos-core-wiki's Introduction

Kokkos

Kokkos: Core Libraries

Kokkos Core implements a programming model in C++ for writing performance portable applications targeting all major HPC platforms. For that purpose it provides abstractions for both parallel execution of code and data management. Kokkos is designed to target complex node architectures with N-level memory hierarchies and multiple types of execution resources. It currently can use CUDA, HIP, SYCL, HPX, OpenMP and C++ threads as backend programming models with several other backends in development.

Kokkos Core is part of the Kokkos C++ Performance Portability Programming Ecosystem.

Kokkos is a Linux Foundation project.

Learning about Kokkos

To start learning about Kokkos:

Obtaining Kokkos

The latest release of Kokkos can be obtained from the GitHub releases page.

The current release is 4.3.01.

curl -OJ -L https://github.com/kokkos/kokkos/archive/refs/tags/4.3.01.tar.gz
# Or with wget
wget https://github.com/kokkos/kokkos/archive/refs/tags/4.3.01.tar.gz

To clone the latest development version of Kokkos from GitHub:

git clone -b develop  https://github.com/kokkos/kokkos.git

Building Kokkos

To build Kokkos, you will need to have a C++ compiler that supports C++17 or later. All requirements including minimum and primary tested compiler versions can be found here.

Building and installation instructions are described here.

You can also install Kokkos using Spack: spack install kokkos. Available configuration options can be displayed using spack info kokkos.

For the complete documentation: kokkos.org/kokkos-core-wiki/

Support

For questions find us on Slack: https://kokkosteam.slack.com or open a GitHub issue.

For non-public questions send an email to: crtrott(at)sandia.gov

Contributing

Please see this page for details on how to contribute.

Citing Kokkos

Please see the following page.

License

License

Under the terms of Contract DE-NA0003525 with NTESS, the U.S. Government retains certain rights in this software.

The full license statement used in all headers is available here or here.

kokkos-core-wiki's People

Contributors

ajpowelsnl avatar antoinemeyer5 avatar brian-kelley avatar crtrott avatar cz4rs avatar dalabre avatar dalg24 avatar davidpoliakoff avatar dsunder avatar e10harvey avatar fnrizzi avatar gshipman avatar hcedwar avatar ibaned avatar janciesko avatar jbludau avatar jeffmiles63 avatar ldh4 avatar marcinwrobel1986 avatar masterleinad avatar mhoemmen avatar ndellingwood avatar nliber avatar nmm0 avatar philmiller avatar pierrepebay avatar rl-s avatar rombur avatar sbte avatar swbova avatar

Stargazers

avatar

Watchers

avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar

Forkers

dalg24 philmiller masterleinad nexgenanalytics nmm0 ldh4 cz4rs rombur nersc crtrott ajpowelsnl jbludau fnrizzi marcinwrobel1986 nliber ibaned azrael3000 brian-kelley cwpearson rgayatri23 tcclevenger pierrepebay antoinemeyer5 multiphasecfd vlkale everbeek17 e10harvey mperrinel sbte aaronyicongfu mfdeakin kowerkoint cedricchevalier19 cartoonist cexa-project guspan-tanadi thierryantoun rl-s rb214678 philipdeegan

kokkos-core-wiki's Issues

Add documentation for HIPManagedSpace

We should add documentation and possibly an example for the new HIPManagedSpace. This is especially delicate as there is a lot of cases in which the user will not really get what is expected (talking about page migration, the xnack issues and what it falls back onto if not available). Furthermore, there is the issue that the user should not be calling MemAdvise on a pointer that is managed by kokkos as it might break things.

We should not forget to also talk about unmanaged views and what we expect from the underlying memory in terms of grained-ness ... It might be worth documenting this for all backends

sphinx porting stage2: update API pages to use sphinx syntax

  • make a list of the API pages/features that need to be updated in priority order
    1. View
    2. all the ones inside containers
    3. convert all parallel dispatch
    4. TBD
  • after the list is approved by the team, make PR for each one to convert it from the "old" syntax to the "new" syntax

By "new syntax" we mean the syntax that @nmm0 proposed to use, see here

Templates for marking `deprecated`, `promoted`, etc. in the documentation

Since we do not host multiple versions of the documentation, we should think about some easy and transparent way to mark things that changed depending on the Kokkos version in our single-source documentation.
To start, I propose the following categories as a discussion starter:

  • promoted -> things that are moved out of Experimental into the main namespace in a version.
  • deprecated -> things that are deprecated in ... and will be removed in ...
  • since and until -> not sure if we need a until it is similar to deprecated, but a since would make sense for newly introduced things
  • behavior change -> hint on a change of behavior in a certain version (e.g. commandline argument parsing)

We should make this as easy to spot as possible, e.g. the user should see it at first glance when looking at the documentation so users can help themselves.

For the HIPSpaces I already faced this problem and used this (see it as a proposal of how it could look like)
image

Damien did something for the documentation of the ScopeGuard as a next example
image

Kokkos random number documentation incomplete

Issue to document that we have work to do here
From Slack:

Hello! It looks like the random number documentation might be incomplete at the moment. Can you point me to an example of how to generate random numbers with Kokkos?

I just saw, that the documentation for fill_random is incomplete too.

Custom sphinx directive for deprecating a type alias

What this issue is about

To show what is needed to define and implement a new custom sphinx directive .. cpp:deprecated-type::.
(Note that the scope of this is to only look at the customization feasibility, not yet at inlining the text and all other things we discussed. Those will be addressed in different issues).

The goal is to minimize the about of customization we have to do to the sphinx code, and delegate as much as possible of the customization to the html level.

Implementation of this custom directive

To support that, we need to modify the cpp domain via the following modification in this file sphinx/domains/cpp.py

# line 3097
	elif objectType == 'deprecated-type':  # just the name
            res.append(symbol.get_full_nested_name().get_id(version))

# line 3129
	elif objectType == 'deprecated-type':  # just the name
            res.append(symbol.get_full_nested_name().get_id(version))

# line 3154
        elif self.declSpecs.outer == 'deprecated-type':
            return '[DEPRECATED]'

# line 4029
	elif self.objectType == 'deprecated-type':
            prefix = self.declaration.get_type_declaration_prefix()
            mainDeclNode += addnodes.desc_sig_keyword(prefix, prefix)
            mainDeclNode += addnodes.desc_sig_space()

# line 6251
        if outer not in ('type', 'member', 'function', 'templateParam', 'deprecated-type'):
            raise Exception('Internal error, unknown outer "%s".' % outer)

# line 6335
        if paramMode not in ('type', 'function', 'operatorCast', 'new', 'deprecated-type'):

# line 6503
        if outer not in ('type', 'member', 'function', 'operatorCast', 'templateParam', 'deprecated-type'):

# line 6507
        if outer in ('type', 'function', 'deprecated-type'):

# line 6522
        elif outer == 'deprecated-type':
            desc = "If just a name"

# line 6537
        elif outer == 'deprecated-type':
            desc = "If typedef-like declaration"

# line 6551
        elif outer == 'deprecated-type':
            header = "Deprecated-type must be either just a name or a "
            header += "typedef-like declaration."

# line 6573
            elif outer == 'deprecated-type':
                paramMode = 'deprecated-type'
                outer = None

# line 6589
        if outer:
            assert outer in ('type', 'member', 'function', 'templateParam', 'deprecated-type')

# line 6963
	if objectType not in ('class', 'union', 'function', 'member', 'type',
                              'concept', 'enum', 'enumerator', 'deprecated-type'):
            raise Exception('Internal error, unknown objectType "%s".' % objectType)
        if directiveType not in ('class', 'struct', 'union', 'function', 'member', 'var', 'type', 'concept', 'enum',
                                 'enum-struct', 'enum-class', 'enumerator', 'deprecated-type'):
            raise Exception('Internal error, unknown directiveType "%s".' % directiveType)

# line 6978
	if objectType in ('type', 'concept', 'member', 'function', 'class', 'deprecated-type'):

# line 7001
	elif objectType == 'deprecated-type':
            prevErrors = []
            pos = self.pos
            try:
                if not templatePrefix:
                    declaration = self._parse_type(named=True, outer='type')
            except DefinitionError as e:
                prevErrors.append((e, "If typedef-like declaration"))
                self.pos = pos
            pos = self.pos
            try:
                if not declaration:
                    declaration = self._parse_type_using()
            except DefinitionError as e:
                self.pos = pos
                prevErrors.append((e, "If type alias or template alias"))
                header = "Error in type declaration."
                raise self._make_multi_error(prevErrors, header) from e

# line 7344
	class CPPDeprecatedTypeObject(CPPObject):
    		object_type = 'deprecated-type'

# line 7794
	'deprecated-type': CPPDeprecatedTypeObject,

# line 7816
	'deprecated-type': CPPXRefRole(),

Example rst source

``Kokkos::TestView``
====================

.. role:: cpp(code)
   :language: cpp

Header File: ``Kokkos_Core.hpp``

Class Interface
---------------

.. cpp:class:: template <class DataType, class... Traits> TestView

  A potentially reference counted multi dimensional array with compile time layouts and memory space.
  Its semantics are similar to that of :cpp:`std::shared_ptr`.

  .. rubric:: Public Member Variables

  .. cpp:member:: static constexpr unsigned rank

    the rank of the view (i.e. the dimensionality).

  .. cpp:type:: const_data_type

    The const version of ``DataType``, same as ``data_type`` if that is already const.

  .. cpp:deprecated-type:: some_deprecated_data_type

    The const version of some_deprecated_data_type.

Overwriting the style for this deprecated directive

What shown above is just the sphinx syntax, but we also need a final step to change the html similarly
to how we do the edit buttom. To do that, the code is (which we will put into a file called change_style_directives.py or similar):

# ...
# Overwriting the deprecated style
str_to_replace = '<span class="pre">[DEPRECATED]</span>'
replaced_with = '<span class="pre" style="color:#A020F0;font-weight:bold;">[DEPRECATED]</span>'
html_str_replace = html_str_replace.replace(str_to_replace, replaced_with)

Rendered as:

Zrzut ekranu z 2022-09-13 16-07-10
Zrzut ekranu z 2022-09-13 16-07-20

[do not close] Sphinx porting TASK 1 work plan

Legend: FR = Francesco, MW = Marcin

  • propose and decide the structure of the new website
  • copy the content of the current kokkos wiki (keeping file formats as they are, i.e. md, etc) to the new thing
  • decide where in the Kokkos organization this new website has to go (kokkos team)
  • set up CI with constraints and autodeploy
  • transition API from markdown to rst following the style Francesco/Nick have prototyped

set up CI and autobuild for sphinx

the "reference" source is all in the main branch under /docs.
We need to setup the automated workflow so that when we do a merge into main, the website gets built and deployed.

Document reduction_identity

The traits class Kokkos::reduction_identity is mentioned in documentation of Built In Reducers and ReducerConcept, but is not actually described in full anywhere I could find.

Document SIMD

  • Create RST format API documentation for simd and simd_mask classes
  • Create Markdown format programming guide documentation for SIMD classes

Document use of nvcc_wrapper and interaction with CMake configuration

https://kokkos.github.io/kokkos-core-wiki/building.html makes no mention of nvcc_wrapper. Ideally, it would be transparent, but that doesn't always work out.

At the very least, we need to document how users building for the CUDA backend can/should configure what host compiler to use. Per @masterleinad

What is the compiler picked up by CMake? If it is nvcc_wrapper you can set the environment variable NVCC_WRAPPER_DEFAULT_COMPILER to the host compiler you want to use. Otherwise, nvcc_wrapper is used implicitly with the host compiler set to the CMake C++ compiler set by CMAKE_CXX_COMPILER

So, we can probably add something along the lines of

When the CUDA backend is enabled, Kokkos will by default use the nvcc-based toolchain. Kokkos will implicitly try to use its included nvcc_wrapper which supports options and behaviors that are more compatible with common host compilers like GCC and Clang. To select the host compiler that nvcc will use, define -DCMAKE_CXX_COMPILER=/path/to/host/compiler

How to document something that is still in `Experimental`

So if we want to keep the documentation close to develop and the prs on develop close to documentation (that the pr would imply/require), we probably will want some 'thing' that lets us write documentation for e.g. a backend that is not yet complete.
Do we have any ideas how to integrate something like this in a neat manner?

@marcinwrobel1986 is there a way to have a switch on the documentation website that would toggle displaying stuff that is marked Experimental?

`cppkokkos` extension: status and next steps

Scope: creating a customized framework for Kokkos documentation

This has two main pieces in it:

  • (a) using custom directives at the sphinx level
  • (b) customizations done directly at the html level.
    Part (b) is needed/useful if sphinx customizations are not possible at all or when doing so is very complicated.

Things done so far

1. Enabled customizations at the sphinx level: what and how

  • used the external feature of Sphinx to create a customization capability that allows us to easly add new customizations without having to modify the upstream sphinx package/code

  • the goal is to create custom directive for C++ documentation: to do so, we had to make a new "domain name" cppkokkos inside of which to create these customizations

  • the PR for this custom domain name lives HERE: NOTE: we need to redo this on top of the latest Sphinx to make sure we are good

2. List of custom directives added to the above new domain that are ready

[DEPRECATED] (.. cppkokkos:deprecated-type::)

See example: HERE

image

image

[DEPRECATED since X.X.X] (.. cppkokkos:deprecated-type::)

See example: HERE

image

image

removed rendering word type before (.. cppkokkos:type::)

Zrzut ekranu z 2022-10-19 16-10-08
Zrzut ekranu z 2022-10-19 16-00-26
Zrzut ekranu z 2022-10-19 16-00-11

3. Customizations applied directly to the html

  • support for custom color for code block directives (postprocessing with edit_button_handler.py)

TODO:

  • define which other code block directives needs to be supported
  • what else should be added to cppkokkos extension

Useful links:

Please write in comments if you have already agreed on other directives which should be added to cppkokkos extension.
@fnrizzi @crtrott @ajpowelsnl @JBludau @dalg24 @nmm0 @masterleinad

sphinx porting: things to add

  • more visible link to GH page (maybe repo icon at the top?)

    • propose a few ways to do this
    • we pick one
    • finalize

  • we need to make sure each doc page when rendered has a visible link to its rst or md file int the source repo so that if one notices typos or things, one can easily click on the link and be taken to edit that page directly

    • figure out ways to do this and propose
    • we pick one
    • finalize

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.