kokkos/programmingguide

Programing guide

programmingguide's Issues

parallel_scan example is wrong

ProgrammingGuide/Kokkos_PG_ParallelDispatch.tex

Line 396 in 7b0817f

upd += x(i);

Kokkos::parallel_scan example is wrong because it aliases input and output arrays. Final result will (incorrectly) be zero. For example, think of what happens on zeroth iteration (i=0).

Wiki Document Update Identification

The Programming Guide and API Reference need to be completed.

As of today, the public (wiki) version and private version (this site) are consistent as I made "editorial" changes only to clean up both sites, including corrects in the Home index.

Please use this "issue" to identify contributions made (dates) so that R&A can be performed more easily. Maybe this will facilitate our updating of the public wiki (which was identified at ORNL18 as being very helpful).

Develop Footnote Solution

The ProgrammingGuide has several footnotes in the .tex version. Develop a method to represent footnotes in the wiki.

Maybe somehow split topics into memory space and execution spaces overall?

Need to separate out what is associated with memory and what is really execution. Imagine a new developer saying.. "I have an issue with my data structure, which section should I read?"

Assignments for Documentation

Go to https://github.com/kokkos/ProgrammingGuide/wiki/API-Alphabetical to find the links!
Example for a class description: https://github.com/kokkos/ProgrammingGuide/wiki/Kokkos%3A%3AView

Example for a function description:
https://github.com/kokkos/ProgrammingGuide/wiki/Kokkos%3A%3Aparallel_for

You need to potentially create the pages, and also get them integrated in the hierarchy of content listing.

Assignee	Class/Function
@crtrott	atomic_exchange
@crtrott	atomic_compare_exchange
@crtrott	atomic_compare_exchange_strong
@crtrott	atomic_load
@crtrott	atomic_[op]
@crtrott	atomic_fetch_[op]
@crtrott	atomic_[op]_fetch
@crtrott	atomic_store
@jeffmiles63	BAnd
@jeffmiles63	BOr
@crtrott	complex
@ibaned	create_mirror
@ibaned	create_mirror_view
@dhollman	Cuda
@dhollman	CudaSpace
@dhollman	CudaUVMSpace
@dhollman	CudaHostPinnedSpace
@dhollman	ExecutionSpaceConcept
@dhollman	HostSpace
@dhollman	HPX
@jeffmiles63	LAnd
@jeffmiles63	LOr
@jeffmiles63	Max
@jeffmiles63	MaxLoc
@dhollman	MDRangePolicy
@dhollman	MemorySpaceConcept
@dhollman	OpenMP
@dhollman	OpenMPTarget
@jeffmiles63	Min
@jeffmiles63	MinLoc
@jeffmiles63	MinMax
@jeffmiles63	MinMaxLoc
@jeffmiles63	parallel_for
@jeffmiles63	parallel_reduce
@jeffmiles63	parallel_scan
@dhollman	PerTeam
@dhollman	PerThread
@jeffmiles63	Prod
@dhollman	RangePolicy
@crtrott	realloc
@jeffmiles63	ReducerConcept
@ndellingwood	resize
@dhollman	SpaceAccessibility
@ndellingwood	(X)subview
@jeffmiles63	Sum
@dhollman	TeamHandleConcept
@dhollman	TeamPolicy
@dhollman	TeamThreadRange
@dhollman	TeamVectorRange
@dhollman	ThreadVectorRange
@crtrott	View

Correctness Checks

Two non-editorial changes were made; verify that these changes are acceptable and correct.

• Section 6.2.1, 3rd paragraph : "at least" changed to "at most" ?? correct or not?
  see this link
• Section 7.1.3: update CUDA version number? ( "At the time of writing CUDA 7.5 supports ...." was changed to CUDA 8.0.
  see this link

Document Reference in Section 2.1.1

Document Section 2.1.1: There is a reference in this section (3rd sentence) to abstract machine models for Exascale computing; what is this document?

Tutorial Exercises - Calling KokkosKernels from Kokkos

KokkosKernels Interface: Inner Product

• Goal: re-implement the inner product exercise using
  1. KokkosKernels BLAS functions
  2. KokkosKernels team-based BLAS function

• Details: <y,A*x>
  - y is N x1, A is N x M , x is M x1
  - Look for comments labeled with “EXERCISE”
  - Compile and run on OpenMP, CUDA backends
  - Compare performance of these two implementations
  - Try LayoutLeft and LayoutRight
  

Using KokkosKernels BLAS functions:

• Convert from hierarchical parallel execution to using BLAS functions
• tmp = A*x
• result = <y,tmp>
• Hint:
  result = KokkosBlas::dot(x,y) performs result = SUM_i(y[i]*x[i])
KokkosBlas::gemv(“N”,alpha,A,x,beta,y) performs matrix-vector multiplication y[i] = beta*y[i] + alpha*SUM_j(A[i,j]*x[j])

Using KokkosKernels team-based BLAS function:

• Same as hierarchical parallel execution
• Call team-based dot within each team to perform <A[teamId,:],x>
• Hint: KokkosBlas::Experimental::dot(teamId,x,y) performs result = SUM_i(y[i]*x[i]) within each thread team

KokkosKernels Interface: Conjugate Gradient Solver

• Goal: implement conjugate gradient solver for square, symmetric, positive-definite sparse matrix

• Details: A*x=b
  - b is N x1, A is N x N symmetric, positive-definite sparse matrix, x is N x1
  - Look for comments labeled with “EXERCISE”
  - Use KokkosKernels BLAS and KokkosKernels Sparse BLAS
  - Sparse matrix generation is provided
  - Compile and run on OpenMP, CUDA backends
  - Vary problem size: -N #
  - Compare performance of CPU vs GPU
  - Hint:
  result = KokkosBlas::dot(x,y) performs result = SUM_i(y[i]*x[i])
KokkosBlas::axpy(alpha,x,y) performs y[i] = y[i] + alpha*x[i]
KokkosBlas::axpby(alpha,x,beta,y) performs y[i] = beta*y[i] + alpha*x[i]
KokkosSparse::spmv(“N”,alpha,A,x,beta,y) performs sparse matrix-vector multiplication y[i] = beta*y[i] + alpha*SUM_j(A[i,j]*x[j])

Complete Tables

Tables 4.1 and 4.2 need to be completed. Their structure can be improved to make them more readable.

HTML Converters

Editors (or Translators) have been suggested for getting the Programming Guide established as a wiki page - Markdown (Dan) and Pandoc (Fernanda) (https://pandoc.org). Do Markdown and Pandoc work on the .tex files? Or does a PDF need to be created?

The Github Wiki itself presents various editors ( Edit mode ) as options for direct creation. My plan is to simply edit in the text (cut and paste from Kokkos_PG_*.tex files) and then mark the insertions appropriately for formatting. This i will begin today unless I hear otherwise.

Convert Figures to PNG Files and Commit to repo

The figures in ProgrammingGuide/figures must be converted to jpeg, png or ?? in order to be displayed in the wiki. Using Linux tool 'convert', generate a .png file from each .pdf file and commit it to directory figures.

In View section, emphasize memory over execution spaces

This is what Christian meant by the section titled "Managing Data Placement" in the chapter on View.

Also, please emphasize memory space over execution space, and talk about the UVM and pinned variants of CudaSpace.

Put parallel dispatch section before View section?

If we put parallel dispatch before View, we can show examples of initializing Views using parallel_for (for example). On the other hand, if we put View before parallel dispatch, examples of the latter can use Views.

.tex to Markdown Conversion

In Progress:
Ch 7
To Do:
Ch 8 (HeirPara)
Ch 9 (CustomReduct - fill in?)
Ch 10 (Atomics - no chapter in 2015 PG document)
Ch 12 (Interoperability)

kokkos-abstractions.pdf missing from figures folder

This figure is used in tex file Kokkos_PG_ProgrammingModel.tex at line 10, which would correspond to Ch 3 page 15, figure 3.1 of the compiled programming guide.

Information, Revisions, Corrections, Questions to Complete PG Wiki

The following items are currently needed to complete the wiki page:
This is Duane's status on the Wiki version of the Programming Guide

1. Section 2.1.1 - reference for ECP machine model discussion
2. convert Chapter 2 figures from pdf to png and commit to code repo ( kokkos/programmingguide/figures )
3. Update compiler list in Section 4.1 ( see kokkos/README file )
4. complete Tables 4.1 and 4.2
5. wiki solution for footnotes
6. CHANGE in Section 6.2.1, 3rd paragraph : "at least" changed to "at most" ?? correct or not?
7. Section 7.1.3: update CUDA version number? ( "At the time of writing CUDA 7.5 supports ...."
8. to complete (tex into html/markdown): Ch 7 (in progress)
9. to start: Ch 8 (HeirPara), Ch 9 (CustomReduct - fill in?), Ch 10 (Atomics - no chapter in 2015 doc), Ch 12 (Interoperability)
10. review all ( Ch 1, 2 done )
11. how to label this doc, title-wise? R&A? post?

PDF Builds but Incorrectly (Improperly placed Chapter Titles and Blank References)

I cloned the Programming Guide and made some editorial changes (less than two dozen editorial-type corrections) to the .tex files. Whether I use the build instructions in this repo ( README file : pdflatex Kokkos_PG ) or the target in the repo Makefile ( make Kokkos_PG ), the result is the same. ( Note, the goal of these builds is to create a PDF of the Programming Guide. )

The problems are 1) chapter headings which overlay the apparently correctly built document a quarter of the way down the first page of the chapter and 2) in-document references that point to other locations in the document which fail to be evaluated and inserted ( left as ? marks ).

Apps using Kokkos

Status:

• Production (i.e. runs science/engineering problems)
• Porting (app decided to use it, but not yet ready for actual runs)
• Evaluation (looking at using Kokkos but no firm decision)
• Training/Education (for example used in University classes for parallel programming)

AppName	Area	Institution	Website	Status	Uses KokkosKernels	Contact Name	Contact Email	Can we mention APP	Can we refer other people
Albany	Climate	Sandia	https://github.com/gahansen/Albany	Porting	Y	Andy Salinger	-	Y	Y
Alexa	Shock Hydrodynamics	Sandia	-	Production	Y	Dan Ibanez	-	Y	Y
Aria	Thermal Fluid Multi Physics	Sandia		Porting	Y	Jonathan Clausen	[email protected]	Y	Y
LAMMPS	Molecular Dynamics	Sandia	https://github.com/lammps/lammps	Production	N	Stan Moore	-	Y	Y
Trilinos-Tpetra	Distributed Sparse Linear Algebra Package	Sandia	https://github.com/trilinos/trilinos	Production	Y	Karen Devine	-	Y	Y
Parallel Research Kernels	Programming Models Research	Intel Corporation	https://github.com/ParRes/Kernels	Evaluation	N	Jeff Hammond	[email protected]	Y	Y
Compadre Toolkit	Compatible remap and PDE solution on particles using Generalized Moving Least Squares	Sandia	-	Production	N	Paul Kuberry	[email protected]	Y	Y
HOMMEXX	Atmospheric Dynamics for Climate Simulations	Sandia		Production	Y	Andy Salinger	[email protected]	Y	?
MiniMD	Molecular Dynamics Proxy App	Sandia	https://github.com/mantevo/minimd	Production	N	Christian Trott	[email protected]	Y	Y
ExaMiniMD	Molecular Dynamics Proxy App	Sandia	https://github.com/ecp-copa/examinimd	Production	N	Christian Trott	[email protected]	Y	Y
MiniFE	Finite Element Proxy App	Sandia	https://github.com/mantevo/minife	Production	N	Christian Trott	[email protected]	Y	Y
GEMPIC	PIC Plasma Physics	Max Planck Institut Munich	-	?	N	Victor Artigues	[email protected]	?	?
AllRegime	CFD, All Mach number Hydrodynamics on regular grids	CEA	-	Porting	N	Thomas Padioleau	[email protected]	yes	yes
ppkMHD	CFD, High order schemes for high Mach number MHD applications in astrophysics	CEA	-	Porting	N	Pierre Kestener	[email protected]	yes	yes
LBM_saclay	Lattice Boltzmann methods for multiphase flow	CEA	-	Evaluation	N	Alain Cartalade / Pierre Kestener	[email protected]; [email protected]	yes	yes
KARFS	Direct numerical simulations of reacting flows with detailed chemistry using many-core/GPU acceleration	KAUST	Production?	?	?	?	?	?
NekMesh	high-order mesh generator	Imperial College London / University of Exeter	?	Production?	?	Jan Eichstaedt	[email protected]	?	?
Faster	SeismicStuff	CSCS	-	Production	Y	-	-	?	?

Update company info?

@crtrott Do details like company info need to be updated and a new copy of the pdf added to Kokkos for the 3.0 copyright? Or does that info remain unchanged since the ProgrammingGuide was written as a SAND report?

Compiler List Update

Update compiler list in Section 4.1 ( see kokkos/README file )

Document Review by Team

Review the Wiki Document

• dal completed chapters 1, 2
• other reviewers

Version Specs for CUDA

Section 4.4 (Compiling for CUDA section) makes statements about a couple of compiler version numbers;
these should be checked and statements made to be accurate.

1. whether Clang 4.0 has been released at the time of this document release or not
   and
2. specification of a version number for NVCC (requested)

Testing github integration - this is a new issue

this is an issue body

Merge "Machine model" and "Programming model" sections?

They currently overlap quite a bit.

Add section on config & build for Intel Xeon Phi (MIC)

Kokkos webpage design and content discussion