oneMKL: update architecture

spencerpatty · petercad · mkrainiuk · rscohn2 · commit 61e21fdc1e3e · 2020-05-28T18:06:13.000-04:00
Co-authored-by: Caday, Peter &lt;peter.caday@intel.com&gt;
Co-authored-by: Kraynyuk, Maria &lt;maria.kraynyuk@intel.com&gt;
Co-authored-by: O'Connell, John &lt;john.oconnell@intel.com&gt;
diff --git a/source/elements/oneMKL/source/architecture/api_design.inc.rst b/source/elements/oneMKL/source/architecture/api_design.inc.rst
@@ -1,8 +1,9 @@
 .. _onemkl_api_design:
 
-API design in oneMKL
-----------------------
-This section discusses the general features of oneMKL API design.
+API Design
+-----------
+
+This section discusses the general features of oneMKL API design. In particular, it covers the use of namespaces and data types from C++, from DPC++ and new ones introduced for oneMKL APIs.
 
 .. _onemkl_namespaces:
 
@@ -34,18 +35,18 @@ oneMKL uses C++ STL data types for scalars where applicable:
 * Integer scalars are C++ fixed-size integer types (``std::intN_t``, ``std::uintN_t``).
 * Complex numbers are represented by C++ ``std::complex`` types.
 
-In general, scalar integer arguments to oneMKL routines are 64 bit integers (``std::int64_t`` or ``std::uint64_t``). Integer vectors and matrices may have varying bit widths, defined on a per-routine basis.
+In general, scalar integer arguments to oneMKL routines are 64-bit integers (``std::int64_t`` or ``std::uint64_t``). Integer vectors and matrices may have varying bit widths, defined on a per-routine basis.
 
 .. _onemkl_dpcpp_datatypes:
 
 DPC++ datatype usage
 ++++++++++++++++++++
 
-oneMKL uses following SYCL Language data types and DPC++ Language Extensions data types:
+oneMKL uses the following DPC++ data types:
 
 * SYCL queue ``sycl::queue`` for scheduling kernels on a SYCL device. See :ref:`onemkl_queues` for more details.
-* SYCL buffer ``sycl::buffer`` for buffer based memory access. See :ref:`onemkl_buffers` for more details.
-* DPC++ Extension Unified Shared Memory (USM) for pointer based memory access. See :ref:`onemkl_usm` for more details.
+* SYCL buffer ``sycl::buffer`` for buffer-based memory access. See :ref:`onemkl_buffers` for more details.
+* Unified Shared Memory (USM) for pointer-based memory access. See :ref:`onemkl_usm` for more details.
 * SYCL event ``sycl::event`` for output event synchronization in oneMKL routines with USM pointers. See :ref:`onemkl_synchronization_with_usm` for more details.
 * Vector of SYCL events ``sycl::vector_class<sycl::event>`` for input events synchronization in oneMKL routines with USM pointers. See :ref:`onemkl_synchronization_with_usm` for more details.
 
@@ -54,7 +55,7 @@ oneMKL uses following SYCL Language data types and DPC++ Language Extensions dat
 oneMKL defined datatypes
 ++++++++++++++++++++++++
 
-oneMKL linear algebra routines use scoped enum types as type-safe replacements for the traditional character arguments used in BLAS and LAPACK.  These types all belong to the ``onemkl`` namespace.  
+oneMKL dense and sparse linear algebra routines use scoped enum types as type-safe replacements for the traditional character arguments used in C/Fortran implementations of BLAS and LAPACK. These types all belong to the ``onemkl`` namespace.  
 
 Each enumeration value comes with two names: A single-character name (the traditional BLAS/LAPACK character) and a longer, more descriptive name. The two names are exactly equivalent and may be used interchangeably.
 
@@ -180,3 +181,22 @@ Each enumeration value comes with two names: A single-character name (the tradit
               -  ``offset::row``
               -  The offset to apply to the output matrix is a row offset, that is to say all the rows in the ``C_offset`` matrix are the same and given by the elements in the ``co`` array.
 
+      .. rubric:: index_base
+         :name: index_base
+         :class: sectiontitle
+
+      The ``index_base`` type specifies how values in index arrays are interpreted. For instance, a sparse matrix stores nonzero values and the
+      indices that they correspond to.  The indices are traditionally provided in one of two forms: C/C++-style using zero-based
+      indices, or Fortran-style using one-based indices. The ``index_base`` type can take the following values:
+
+      .. container:: tablenoborder
+
+         .. list-table::
+            :header-rows: 1
+
+            * -  Name
+              -  Description
+            * -  ``index_base::zero``
+              -  Index arrays for an input matrix are provided using zero-based (C/C++ style) index values.  That is, indices start at 0.
+            * -  ``index_base::one``
+              -  Index arrays for an input matrix are provided using one-based (Fortran style) index values.  That is, indices start at 1.
diff --git a/source/elements/oneMKL/source/architecture/architecture.rst b/source/elements/oneMKL/source/architecture/architecture.rst
@@ -3,8 +3,16 @@
 oneMKL Architecture
 ====================
 
+The oneMKL element of oneAPI has several general assumptions, requirements and recommendations for all domains contained therein.  These will be addressed in this architecture section.  
+In particular, DPC++ allows for a great control over the execution of kernels on the various devices.  We discuss the supported execution models of oneMKL APIs in :ref:`onemkl_execution_model`. 
+A discussion of how data is stored and passed in and out of the APIs is addressed in :ref:`onemkl_memory_model`.
+The general structure and design of oneMKL APIs including namespaces and common data types are expressed in :ref:`onemkl_api_design`.
+The exceptions and error handling are described in :ref:`onemkl_exceptions`.  
+Finally all the other necessary aspects related to oneMKL architecture can be found in :ref:`onemkl_arch_other` including versioning and discussion of pre and post conditions. 
+
+
 .. include:: execution_model.inc.rst
 .. include:: memory_model.inc.rst
 .. include:: api_design.inc.rst
 .. include:: exceptions.inc.rst
-.. include:: global_library_controls.inc.rst
+.. include:: other_architecture.inc.rst
diff --git a/source/elements/oneMKL/source/architecture/exceptions.inc.rst b/source/elements/oneMKL/source/architecture/exceptions.inc.rst
@@ -1,7 +1,7 @@
 .. _onemkl_exceptions:
 
-oneMKL Exceptions
-------------------
+Exceptions and Error Handling
+------------------------------
 
 Will be added in a future version.
 
diff --git a/source/elements/oneMKL/source/architecture/execution_model.inc.rst b/source/elements/oneMKL/source/architecture/execution_model.inc.rst
@@ -3,14 +3,14 @@
 Execution Model
 ---------------
 
-This section describes the execution environment common to all oneMKL functionality.
+This section describes the execution environment common to all oneMKL functionality. The execution environment includes how data is provided to computational routines in :ref:`onemkl_queues`, support for several devices in :ref:`onemkl_device_usage`, synchronous and asynchronous exection models in :ref:`onemkl_asynchronous_synchronous_execution` and :ref:`onemkl_host_thread_safety`.  
 
 .. _onemkl_queues:
 
-Queues
-++++++
+Use of Queues
++++++++++++++
 
-Will be added in a future version.
+The ``sycl::queue`` defined in the oneAPI DPC++ specification is used to specify the device and features enabled on that device on which a task will be enqueued.  There are two forms of computational routines in oneMKL: class based :ref:`onemkl_member_functions` and standalone :ref:`onemkl_nonmember_functions`.  As these may interact with the ``sycl::queue`` in different ways, we provide a section for each one to describe assumptions.
 
 
 .. _onemkl_nonmember_functions:
@@ -25,7 +25,8 @@ Each oneMKL non-member computational routine takes a ``sycl::queue`` reference a
 All computation performed by the routine shall be done on the hardware device(s) associated with this queue, with possible aid from the host, unless otherwise specified.
 In the case of an ordered queue, all computation shall also be ordered with respect to other kernels as if enqueued on that queue.
 
-A particular oneMKL implementation may not support the execution of a given oneMKL routine on the specified device(s). In this case, the implementation may either perform the computation on the host or throw an exception.
+A particular oneMKL implementation may not support the execution of a given oneMKL routine on the specified device(s). In this case, the implementation may either perform the computation on the host or throw an exception.  See :ref:`onemkl_exceptions` for the possible exceptions.
+
 
 .. _onemkl_member_functions:
 
diff --git a/source/elements/oneMKL/source/architecture/global_library_controls.inc.rst b/source/elements/oneMKL/source/architecture/global_library_controls.inc.rst
diff --git a/source/elements/oneMKL/source/architecture/other_architecture.inc.rst b/source/elements/oneMKL/source/architecture/other_architecture.inc.rst
@@ -0,0 +1,35 @@
+.. _onemkl_arch_other:
+
+Other Features
+----------------
+This section covers all other features in the design of oneMKL architecture.
+
+
+
+.. _onemkl_spec_versioning:
+
+oneMKL Specification Versioning Strategy
++++++++++++++++++++++++++++++++++++++++++
+
+This oneMKL specification uses a ``MAJOR.MINOR.PATCH`` approach for its versioning strategy.  
+The ``MAJOR`` count is updated when a significant new feature or domain is added or backward compatibility is broken.  
+The ``MINOR`` count is updated when new APIs are changed or added or deleted, or language updated with relatively significant change to the meaning but without breaking backwards compatibility.  
+The ``PATCH`` count is updated when wording, language or structure is updated without significant change to the meaning or interpretation.
+
+
+.. _onemkl_spec_current_version:
+
+Current Version of this oneMKL Specification
++++++++++++++++++++++++++++++++++++++++++++++
+
+This is the oneMKL specification version 0.8.0.
+
+
+.. _onemkl_pre_post_conditions:
+
+Pre/Post Condition Checking
++++++++++++++++++++++++++++++++++++++++
+
+The individual oneMKL computational routines will define any preconditions and postconditions and will define in this specification any specific checks or verifications that should be enabled for all implementations.
+
+
diff --git a/source/elements/oneMKL/source/index.rst b/source/elements/oneMKL/source/index.rst
@@ -9,7 +9,9 @@ oneMKL |mkl_version|
 
 The |mkl_full_name| (oneMKL) defines a set of fundamental mathematical routines for use in high-performance computing and other applications. As part of oneAPI, oneMKL is designed to allow execution on a wide variety of computational devices: CPUs, GPUs, FPGAs, and other accelerators. The functionality is subdivided into several domains: dense linear algebra, sparse linear algebra, discrete Fourier transforms, random number generators and vector math.
 
-The general assumptions, design features and requirements for the oneMKL library and its routines will be described in :ref:`onemkl_architecture`.  The individual domains and their APIs are described in :ref:`onemkl_domains`.
+
+The general assumptions, design features and requirements for the oneMKL library and host-to-device computational routines will be described in :ref:`onemkl_architecture`. 
+The individual domains and their APIs are described in :ref:`onemkl_domains`.  
 
 
 .. toctree::
