diff --git a/source/elements/oneMKL/source/architecture/api_design.inc.rst b/source/elements/oneMKL/source/architecture/api_design.inc.rst index c6a98490b6..9e4e4e1697 100644 --- a/source/elements/oneMKL/source/architecture/api_design.inc.rst +++ b/source/elements/oneMKL/source/architecture/api_design.inc.rst @@ -16,27 +16,28 @@ oneMKL namespaces The oneMKL library uses C++ namespaces to organize routines by mathematical domain. All oneMKL objects and routines shall be contained within the ``oneapi::mkl`` base namespace. The individual oneMKL domains use a secondary namespace layer as follows: -======================== ======================================================================================================= -namespace oneMKL domain or content -======================== ======================================================================================================= -``oneapi::mkl`` oneMKL base namespace, contains general oneMKL data types, objects, exceptions and routines -``oneapi::mkl::blas`` Dense linear algebra routines from BLAS and BLAS like extensions. The oneapi::mkl::blas namespace should contain two namespaces column_major and row_major to support both matrix layouts. See :ref:`onemkl_blas` -``oneapi::mkl::lapack`` Dense linear algebra routines from LAPACK and LAPACK like extensions. See :ref:`onemkl_lapack` -``oneapi::mkl::sparse`` Sparse linear algebra routines from Sparse BLAS and Sparse Solvers. See :ref:`onemkl_sparse_linear_algebra` -``oneapi::mkl::dft`` Discrete and fast Fourier transformations. See :ref:`onemkl_dft` -``oneapi::mkl::rng`` Random number generator routines. See :ref:`onemkl_rng` -``oneapi::mkl::vm`` Vector mathematics routines, e.g. trigonometric, exponential functions acting on elements of a vector. See :ref:`onemkl_vm` -======================== ======================================================================================================= +=========================================== ========================================================================= +namespace oneMKL domain or content +=========================================== ========================================================================= +``oneapi::mkl`` oneMKL base namespace, contains general oneMKL data types, objects, exceptions and routines +``oneapi::mkl::blas`` Dense linear algebra routines from BLAS and BLAS like extensions. The oneapi::mkl::blas namespace should contain two namespaces column_major and row_major to support both matrix layouts. See :ref:`onemkl_blas` +``oneapi::mkl::lapack`` Dense linear algebra routines from LAPACK and LAPACK like extensions. See :ref:`onemkl_lapack` +``oneapi::mkl::sparse`` Sparse linear algebra routines from Sparse BLAS and Sparse Solvers. See :ref:`onemkl_sparse_linear_algebra` +``oneapi::mkl::dft`` Discrete and fast Fourier transformations. See :ref:`onemkl_dft` +``oneapi::mkl::rng`` Random number generator routines. See :ref:`onemkl_rng` +``oneapi::mkl::vm`` Vector mathematics routines, e.g. trigonometric, exponential functions acting on elements of a vector. See :ref:`onemkl_vm` +``oneapi::mkl::experimental::data_fitting`` Data fitting routines, e.g. interpolation. See :ref:`data_fitting` +=========================================== ========================================================================= .. note:: :name: Implementation Requirement - Inside each oneMKL domain, there are many routines, classes, enums and objects defined which constitute the breadth and scope of that oneMKL domain. + Inside each oneMKL domain, there are many routines, classes, enums and objects defined which constitute the breadth and scope of that oneMKL domain. It is permitted for a library implementation of the oneMKL specification to implement either all, one or more than one of the domains in oneMKL. However, within an implementation of a specific domain, all relevant routines, classes, enums and objects (including those relevant enums and objects which live outside a particular domain in the general ``oneapi::mkl`` namespace must be both declared and defined in the library so that an application that uses that domain could build and link against that library implementation successfully. - It is however acceptable to throw the runtime exception :ref:`oneapi::mkl::unimplemented` inside of the routines or class member functions in that domain that have not been fully implemented. - For instance, a library may choose to implement the oneMKL BLAS functionality and in particular may choose to implement only the :ref:`onemkl_blas_gemm` api for their library, in which case they must also include all the other blas namespaced routines and throw the :ref:`oneapi::mkl::unimplemented` exception inside all the others. - + It is however acceptable to throw the runtime exception :ref:`oneapi::mkl::unimplemented` inside of the routines or class member functions in that domain that have not been fully implemented. + For instance, a library may choose to implement the oneMKL BLAS functionality and in particular may choose to implement only the :ref:`onemkl_blas_gemm` api for their library, in which case they must also include all the other blas namespaced routines and throw the :ref:`oneapi::mkl::unimplemented` exception inside all the others. + In such a case, the implemented routines in such a library should be communicated clearly and easily understood by users of that library. @@ -73,7 +74,7 @@ oneMKL uses the following DPC++ data types: oneMKL defined datatypes ++++++++++++++++++++++++ -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 ``oneapi::mkl`` 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 ``oneapi::mkl`` 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. @@ -238,7 +239,7 @@ Each enumeration value comes with two names: A single-character name (the tradit :name: layout :class: sectiontitle - The ``layout`` type specifies how a dense matrix ``A`` with leading dimension ``lda`` is stored as one dimensional array in memory. + The ``layout`` type specifies how a dense matrix ``A`` with leading dimension ``lda`` is stored as one dimensional array in memory. The layouts are traditionally provided in one of two forms: C/C++-style using ``row_major`` layout, or Fortran-style using ``column_major`` layout. The ``layout`` type can take the following values: diff --git a/source/elements/oneMKL/source/domains/data_fitting/cubic.rst b/source/elements/oneMKL/source/domains/data_fitting/cubic.rst new file mode 100644 index 0000000000..e6b5ebb2d6 --- /dev/null +++ b/source/elements/oneMKL/source/domains/data_fitting/cubic.rst @@ -0,0 +1,88 @@ +.. SPDX-FileCopyrightText: 2022 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _cubic: + +Cubic Splines +============= + +Cubic splines are splines whose degree is equal to 3. + +Cubic splines are described by the following polynomial + +.. math:: + P_i\left( x \right) = c_{1,i}+ c_{2,i}\left( x - x_i \right) + c_{3,i}{\left( x - x_i \right)}^2+ c_{4,i}{\left( x - x_i \right)}^3, + +where + +.. math:: + x \in \left[ x_i, x_{i+1} \right), + +.. math:: + i = 1,\dots , n-1. + +There are many different kinds of cubic splines: Hermite, natural, Akima, Bessel. +However, the current version of DPC++ API supports only one type: Hermite. + +Header File +----------- + +.. code:: cpp + + #include + +Namespace +--------- + +.. code:: cpp + + oneapi::mkl::experimental::data_fitiing + +Hermite Spline +-------------- + +The coefficients of Hermite spline are calculated using the following formulas: + +.. math:: + c_{1,i} = f\left( x_i \right), + +.. math:: + c_{2,i} = s_i, + +.. math:: + c_{3,i} = \left( \left[ x_i, x_{i+1} \right]f - s_i \right) / \left( \Delta x_i \right) - c_{4,i}\left( \Delta x_i \right), + +.. math:: + c_{4,i} = \left( s_i + s_{i+1} - 2\left[ x_i, x_{i+1} \right]f \right) / {\left( \Delta x_i \right)}^2, + +.. math:: + s_i = f^{\left( 1 \right)}\left( x_i \right). + +The following boundary conditions are supported for Hermite spline: + + - Free end (:math:`f^{(2)}(x_1) = f^{(2)}(x_n) = 0`). + - Periodic. + - First derivative. + - Second Derivative. + +Syntax +^^^^^^ + +.. code:: cpp + + namespace cubic_spline { + struct hermite {}; + } + +Example +^^^^^^^ + +To create a cubic Hermite spline object use the following: + +.. code:: cpp + + spline val( + /*SYCL queue object*/q, + /*number of spline functions*/ny + ); diff --git a/source/elements/oneMKL/source/domains/data_fitting/data-fitting.inc.rst b/source/elements/oneMKL/source/domains/data_fitting/data-fitting.inc.rst new file mode 100644 index 0000000000..d8e8d06b17 --- /dev/null +++ b/source/elements/oneMKL/source/domains/data_fitting/data-fitting.inc.rst @@ -0,0 +1,33 @@ +.. SPDX-FileCopyrightText: 2022 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _data_fitting: + +Data Fitting +============ + +oneMKL provides spline-based interpolation capabilities that can be used for +spline construction (Linear, Cubic, Quadratic etc.), +to perform cell-search operations, and to approximate functions, +function derivatives, or integrals. + +APIs are experimental. It means that no API or ABI backward compatibility are guaranteed. + +APIs are based on SYCL USM (Unfied Shared Memory) input data. + +Routines +-------- + +Splines: + :ref:`splines` +Interpolate function: + :ref:`interpolate` + +.. toctree:: + :maxdepth: 1 + :hidden: + + data_fitting/terms + data_fitting/splines + data_fitting/interpolate diff --git a/source/elements/oneMKL/source/domains/data_fitting/img_data_fitting.png b/source/elements/oneMKL/source/domains/data_fitting/img_data_fitting.png new file mode 100644 index 0000000000..e16ba7d604 Binary files /dev/null and b/source/elements/oneMKL/source/domains/data_fitting/img_data_fitting.png differ diff --git a/source/elements/oneMKL/source/domains/data_fitting/interpolate.rst b/source/elements/oneMKL/source/domains/data_fitting/interpolate.rst new file mode 100644 index 0000000000..ded7fe1be2 --- /dev/null +++ b/source/elements/oneMKL/source/domains/data_fitting/interpolate.rst @@ -0,0 +1,107 @@ +.. SPDX-FileCopyrightText: 2022 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _interpolate: + +Interpolate Function +==================== + +Interpolate function performs computations of function and derivatives values at interpolation sites. + +If the sites do not belong to interpolation interval ``[a, b)``, the library uses: + + - interpolant :math:`I_0` coefficients computed for interval :math:`[x_0, x_1)` for the + computations at the sites to the left of ``a``. + - interpolant :math:`I_{n-2}` coefficients computed for interval + :math:`[x_{n-2}, x_{n-1})` for the computations at the sites to the right of ``b``. + +Interpolation algorithm depends on interpolant's type (e.g., for a cubic spline, +the evaluation of a third-order polynomial is performed to obtain the resulting interpolant value). + +Header File +----------- + +.. code:: cpp + + #include + +Namespace +--------- + +.. code:: cpp + + oneapi::mkl::experimental::data_fitting + +Syntax +------ + +.. code:: cpp + + template + sycl::event interpolate( + Interpolant& interpolant, + typename Interpolant::value_type* sites, + std::int64_t n_sites, + typename Interpolant::value_type* results, + const std::vector& dependencies, + interpolate_hint ResultHint = interpolate_hint::funcs_sites_ders, + site_hint SiteHint = site_hint::non_uniform); // (1) + + template + sycl::event interpolate( + Interpolant& interpolant, + typename Interpolant::value_type* sites, + std::int64_t n_sites, + typename Interpolant::value_type* results, + std::bitset<32> derivatives_indicator, + const std::vector& dependencies = {}, + interpolate_hint ResultHint = interpolate_hint::funcs_sites_ders, + site_hint SiteHint = site_hint::non_uniform); // (2) + + template + sycl::event interpolate( + sycl::queue& queue, + const Interpolant& interpolant, + typename Interpolant::value_type* sites, + std::int64_t n_sites, + typename Interpolant::value_type* results, + const std::vector& dependencies, + interpolate_hint ResultHint = interpolate_hint::funcs_sites_ders, + site_hint SiteHint = site_hint::non_uniform); // (3) + + template + sycl::event interpolate( + sycl::queue& queue, + const Interpolant& interpolant, + typename Interpolant::value_type* sites, + std::int64_t n_sites, + typename Interpolant::value_type* results, + std::bitset<32> derivatives_indicator, + const std::vector& dependencies = {}, + interpolate_hint ResultHint = interpolate_hint::funcs_sites_ders, + site_hint SiteHint = site_hint::non_uniform); // (4) + +For all functions users can provide ``SiteHint`` and ``ResultHint`` to specify +the layout of ``sites`` and ``results`` respectively. +If ``results`` layout doesn't satisfy ``ResultHint`` and/or +``sites`` layout doesn't satisfy ``SiteHint``, behavior is undefined. +Returns the SYCL event of the submitted task. + +Interfaces (3) and (4) can be useful when users try to interpolate over different parts of ``sites`` +using different ``queue`` objects. + +#. Performs computations of function values only using the SYCL queue + associated with ``interpolant``. +#. Performs computations of certain derivatives + (function values is considered as a zero derivative) which are indicated in + ``derivatives_indicator`` (each bit corresponds to certain derivative starting from lower bit) + using the SYCL queue associated with ``interpolant``. +#. Performs computations of function values only using ``queue`` as an input argument + that should be created from the same context and device as the SYCL queue + associated with ``interpolant``. +#. Performs computations of certain derivatives + (function values is considered as a zero derivative) which are indicated in + ``derivatives_indicator`` (each bit corresponds to certain derivative starting from lower bit) + using ``queue`` as an input argument that should be created from + the same context and device as the SYCL queue associated with ``interpolant``. diff --git a/source/elements/oneMKL/source/domains/data_fitting/linear.rst b/source/elements/oneMKL/source/domains/data_fitting/linear.rst new file mode 100644 index 0000000000..ee1501b20f --- /dev/null +++ b/source/elements/oneMKL/source/domains/data_fitting/linear.rst @@ -0,0 +1,64 @@ +.. SPDX-FileCopyrightText: 2022 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _linear: + +Linear Spline +============= + +Linear spline is a spline whose degree is equal to 1. + +It's described by the following polynomial + +.. math:: + P_i\left( x \right) = c_{1,i} + c_{2,i}\left( x - x_i \right), + +where + +.. math:: + x \in \left[ x_i, x_{i+1} \right), + +.. math:: + c_{1,i} = f\left( x_i \right), + +.. math:: + c_{2,i} = \left[ x_i, x_{i+1} \right]f, + +.. math:: + i = 1, \dots, n-1. + +Header File +----------- + +.. code:: cpp + + #include + +Namespace +--------- + +.. code:: cpp + + oneapi::mkl::experimental::data_fitiing + +Syntax +------ + +.. code:: cpp + + namespace linear_spline { + struct default_type {}; + } + +Example +------- + +To create a linear spline object use the following: + +.. code:: cpp + + spline val( + /*SYCL queue object*/q, + /*number of spline functions*/ny + ); diff --git a/source/elements/oneMKL/source/domains/data_fitting/splines.rst b/source/elements/oneMKL/source/domains/data_fitting/splines.rst new file mode 100644 index 0000000000..6b0987968c --- /dev/null +++ b/source/elements/oneMKL/source/domains/data_fitting/splines.rst @@ -0,0 +1,187 @@ +.. SPDX-FileCopyrightText: 2022 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _splines: + +Splines +======= + +Header File +----------- + +.. code:: cpp + + #include + +Namespace +--------- + +.. code:: cpp + + oneapi::mkl::experimental::data_fitiing + +Common API for All Spline Types +------------------------------- + +.. code:: cpp + + template < + typename FpType, + typename SplineType, + int Dimensions = 1> + class spline { + public: + using value_type = FpType; + using spline_type = SplineType; + + spline( + const sycl::queue& queue, + std::int64_t ny = 1, + bool were_coeffs_computed = false); + + spline( + const sycl::device& device, + const sycl::context& context, + std::int64_t ny = 1, + bool were_coeffs_computed = false); + + ~spline(); + + spline(const spline& other) = delete; + spline(spline&& other) = delete; + spline& operator=( + const spline& other) = delete; + spline& operator=( + spline&& other) = delete; + + spline& set_partitions( + FpType* input_data, + std::int64_t nx, + partition_hint PartitionHint = partition_hint::non_uniform); + + spline& set_function_values( + FpType* input_data, + function_hint FunctionHint = function_hint::row_major); + + spline& set_coefficients( + FpType* data, + coefficient_hint CoeffHint = coefficient_hint::row_major); + + bool is_initialized() const; + + std::int64_t get_required_coeffs_size() const; + + sycl::event construct(const std::vector& dependencies = {}); + }; + +An instance of ``spline`` create the ``N``-dimensional spline +that operates with the ``T`` data type. ``ST`` is a type of spline. +``T`` can only be ``float`` or ``double``. + +.. list-table:: + :header-rows: 1 + + * - Constructor + - Description + * - ``spline(const sycl::queue& queue, std::int64_t ny = 1, bool were_coeffs_computed = false);`` + - Create an object with the ``queue`` SYCL queue and ``ny`` number of functions. + If spline coeficients were already computed, provide ``true`` as a 3-rd argument. + ``were_coeffs_computed == false`` by default. + It means that it needs to call ``construct`` to compute spline coefficients. + This constructor is useful when users want to pass SYCL queue, not SYCL device and SYCL context. + * - ``spline(const sycl::device& device, const sycl::context& context, std::int64_t ny = 1, bool were_coeffs_computed = false);`` + - Create an object using the ``device`` SYCL device, the ``context`` context + and ``ny`` number of functions. + If spline coeficients were already computed, provide ``true`` as a 3-rd argument. + ``were_coeffs_computed == false`` by default. + It means that it needs to call ``construct`` to compute spline coefficients. + This constructor is useful for cases mentioned in :ref:`interpolate`. + +.. list-table:: + :header-rows: 1 + + * - Member function + - Description + * - ``spline& set_partitions(FpType* input_data, std::int64_t nx, partition_hint PartitionHint = partition_hint::non_uniform);`` + - Set partition values that are specified by the ``input_data`` memory pointer and ``nx`` partition values. + Users can provide ``PartitionHint`` to specify the layout of data. + Default layout is ``non_uniform``. + If ``uniform`` is specified, ``nx`` must be equal to ``2`` and + ``input_data`` must contain only 2 values corresponding to the left and the right borders + of the sub-interval defined by the partition. + Otherwise, behavior is undefined. + If ``input_data`` layout doesn't satisfy ``PartitionHint``, behavior is undefined. + Returns a reference to the spline object for which partitions are set. + + Example, for ``uniform``. Let :math:`\left\{ i \right\}_{i=1,\dots,n}` be a partition. + So, ``input_data`` must contain only 2 values: 1, ``n``. + * - ``spline& set_function_values(FpType* input_data, function_hint FunctionHint = storage_hint::row_major);`` + - Set function values that are specified by the ``input_data`` memory pointer. + Number of function values must be ``ny * nx`` elements. + Users can provide a ``FunctionHint`` to specify the layout of data with a default value of ``row_major``. + If ``input_data`` layout doesn't satisfy ``FunctionHint``, behavior is undefined. + Returns a reference to the spline object for which function values are set. + * - ``spline& set_coefficients(FpType* data, coefficient_hint CoeffHint = storage_hint::row_major);`` + - Set coefficients that are specified by the ``data`` memory pointer. + Number of coefficients in the memory must equals to the return value of ``get_required_coeffs_size()``. + Users can provide a ``CoeffHint`` to specify the layout of data with a default value of ``row_major``. + If ``data`` layout doesn't satisfy ``CoeffHint``, behavior is undefined. + If ``were_coeffs_computed == false``, ``data`` will be rewritten during ``construct``. + Returns a reference to the spline object for which coefficients are set. + * - ``bool is_initialized() const;`` + - Returns ``true`` if all required data are set (for example, partitions, function values, coefficients). + * - ``std::int64_t get_required_coeffs_size() const;`` + - Returns amount of memory that is required for coefficients storage. + * - ``sycl::event construct(const std::vector& dependencies = {});`` + - Constructs the spline (calculates spline coefficients if ``were_coeffs_computed == false``). + The function submits a SYCL kernel and returns the SYCL event to wait on to ensure computation is complete. + ``dependencies`` is a list of SYCL events to wait for before starting computations. + +There are some splines that requires internal conditions and boundary conditions to be set. +For such spline types, the following member functions must be called. + +.. code:: cpp + + spline& set_internal_conditions( + FpType* input_data); + + spline& set_boundary_conditions( + bc_type BCType = bc_type::free_end, + FpType input_value = {}); + +.. list-table:: + :header-rows: 1 + + * - Member function + - Description + * - ``spline& set_internal_conditions(FpType* input_data);`` + - Set internal conditions that are specified by the ``input_data`` memory pointer. + Number of internal condition values must equals to ``nx - 2``. + Returns a reference to the spline object for which internal conditions are set. + * - ``spline& set_boundary_conditions(bc_type BCType = bc_type::free_end, FpType input_value = {});`` + - Set the ``input_value`` boundary condition corresponding to ``BCType``. + Default value for ``input_value`` is empty since some boundary conditions doesn't require value to be provided. + Returns a reference to the spline object for which boundary condition value is set. + +.. note:: + copy/move constructor and copy/move assignment operators are deleted + since the ``spline`` class is just a wrapper over memory that users provide. + Memory management responsibility is on user's side. + +Supported Spline Types +---------------------- + +Currently, the DPC++ Data Fitting APIs support the following spline types +(follow the corresponding links to deep-dive into the details): + +:ref:`linear` + +:ref:`cubic` + +.. toctree:: + :maxdepth: 1 + :hidden: + + linear + cubic diff --git a/source/elements/oneMKL/source/domains/data_fitting/terms.rst b/source/elements/oneMKL/source/domains/data_fitting/terms.rst new file mode 100644 index 0000000000..acf32027d6 --- /dev/null +++ b/source/elements/oneMKL/source/domains/data_fitting/terms.rst @@ -0,0 +1,334 @@ +.. SPDX-FileCopyrightText: 2022 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _terms: + +Common Terms +============ + +Glossary +-------- + +Assume we need to interpolate a function ``f(x)`` on the ``[a, b)`` interval using splines. + +We define a **partition** of `[a, b)` to be a collection of :math:`n` points +(**partition points**) :math:`\left\{ x_{i}\right\}, i = 1, \dots, n` such as +:math:`a = x_1 < x_2 < \dots < x_n = b`. +In general when there is no condition with respect to the distances between the :math:`x_i`, +the partition is referred to as a **non-uniform partition**. + +Spline has ``k`` degree if it can be expressed by the following polynomial: + +.. math:: + P\left( x \right) = + c_{1} + + c_{2}\left( x - x_i \right) + + c_{3}{\left( x - x_i \right)}^2 + \dots + + c_{k-1}{\left( x - x_i \right)}^k. + +Splines are constructed on the partition subintervals +:math:`[x_i, x_{i+1}), i=1,\dots,n-1` sub-intervals. +So, for each sub-interval there are following polynomials: + +.. math:: + P_i\left( x \right) = + c_{1,i} + + c_{2,i}\left( x - x_i \right) + + c_{3,i}{\left( x - x_i \right)}^2 + \dots + + c_{k-1,i}{\left( x - x_i \right)}^k. + +The scalars :math:`c_{j,i}, j=1,\dots,k, i=1,\dots,n` are called spline **coefficients**. + +Given an interpolant spline of :math:`f(x)` on a partition of :math:`[a,b)`, +the interpolant function can be evaluated at any point in the interval :math:`[a,b)` or +outside it (see :ref:`interpolate` for details). Such points to evaluate the interpolant at +will be referred to as **interpolation sites** or simply **sites**. +Sites can correspond to partition points, but are not required to be. + +.. image:: img_data_fitting.png + :width: 600 + :alt: Data Fitting terminology picture + +Mathematical Notation in the Data Fitting Component +--------------------------------------------------- + +.. list-table:: + :header-rows: 1 + + * - Concept + - Mathematical Notation + * - Partition + - :math:`\left\{ x_i \right\}_{i=1,\dots,n}`, + where :math:`a = x_1 < x_2 < \dots < x_n = b`. + * - Uniform partition + - Partition :math:`\left\{ x_i \right\}_{i=1,\dots,n}` + which meets the following condition: + + :math:`x_{i+1} - x_i = x_i - x_{i-1}, i=2,\dots,n-1` + * - Quasi-uniform partition + - Partition :math:`\left\{ x_i \right\}_{i=1,\dots,n}` + which meets the constraint with a constant ``C`` defined as: + :math:`1 \le M_max / M_min \le C`, + + where + + :math:`M_max = \text{max}_{i=1,\dots,n-1} (x_{i+1} - x_i)`, + + :math:`M_min = \text{min}_{i=1,\dots,n-1} (x_{i+1} - x_i)`, + * - Vector-valued function of dimension ``m`` + - :math:`f(x) = (f_1(x),\dots, f_m(x))`. + * - A ``d``-order derivative of function ``f(x)`` at point ``t`` + - :math:`f^{(d)}(t)`. + * - Function ``p`` agrees with function ``f`` at the points + :math:`\left\{ x_i \right\}_{i=1,\dots,n}`. + - For every point :math:`\zeta` in sequence :math:`\left\{ x_i \right\}_{i=1,\dots,n}` + the equality :math:`p^{(d)}(\zeta) = f^{(d)}(\zeta)` + holds for all :math:`d=0,\dots,s` if ``p`` and ``f`` + are ``s``-times differentiable. + * - The ``k``-th divided difference of function ``f`` at points :math:`x_i,..., x_{i+k}`. + This difference is the leading coefficient of the polynomial of order ``k+1`` + that agrees with ``f`` at :math:`x_i,\dots, x_{i+k}`. + - :math:`\left[ x_i,\dots, x_{i + k} \right]f`. + + In particular, + + :math:`\left[ x_1 \right]f = f(x_1)`, + + :math:`\left[ x_1, x_2 \right] f = (f(x_1) - f(x_2)) / (x_1 - x_2)`. + +Hints in the Data Fitting Component +----------------------------------- + +The oneMKL Data Fitting component provides ways to specify some "hints" +for partitions, function values, coefficients, interpolation sites. + +Partition Hints +^^^^^^^^^^^^^^^ + +The following are supported: + + - Non-uniform. + - Quasi-uniform. + - Uniform. + +**Syntax** + +.. code:: cpp + + enum class partition_hint { + non_uniform, + quasi_uniform, + uniform + }; + +Function Values Hints +^^^^^^^^^^^^^^^^^^^^^ + +Let :math:`\left\{ x_i \right\}_{i=1,\dots,nx}` be a partition, +:math:`\left\{ f_j(x) \right\}_{j=1,\dots,ny}` be a vector-valued function. +Function values are stored in the one-dimensional array with ``nx * ny`` elements. +2 different layouts are possible: row major and column major. + +- For row major layout function values are stored as the following: + + Let :math:`\left\{ f_{j,i} \right\}_{j=1,\dots,ny, i=1,\dots,nx}` + be the function value that corresponds to the ``i-th`` partition point and the ``j-th`` function. + +- For column major: + + Let :math:`\left\{ f_{i,j} \right\}_{i=1,\dots,nx, j=1,\dots,ny}` + be the function value that corresponds to the ``i-th`` partition point and the ``j-th`` function. + +The following hints are supported: + + - Row major. + - Column major. + +**Syntax** + +.. code:: cpp + + enum class function_hint { + row_major, + col_major + }; + +Coefficients Hints +^^^^^^^^^^^^^^^^^^ + +Let :math:`\left\{ x_i \right\}_{i=1,\dots,nx}` be a partition of :math:`[a,b)` and +:math:`f(x) = \left\{ f_j(x) \right\}_{j=1,\dots,ny}` be a vector-valued function +to be interpolated with a cubic spline on this partition. +To create a cubic spline, on each sub-interval in the partition, we require 4 coefficients per component :math:`f_j(x)` of :math:`f(x)`. The coefficients are stored in a one-dimensional array with :math:`4 * (nx - 1) * ny` elements. + +- For row major: + + Let :math:`\left\{ c_{j,i,k} \right\}_{j=1,\dots,ny, i=1,\dots,nx-1, k=1,\dots,4}` + be the coefficient value that corresponds to the ``i-th`` partition point, the ``j-th`` function. + +- For column major: + + Let :math:`\left\{ c_{i,j,k} \right\}_{i=1,\dots,nx-1, j=1,\dots,ny, k=1,\dots,4}` + be the coefficient value that corresponds to the ``i-th`` partition point, the ``j-th`` function. + +The following is supported: + + - row major + +**Syntax** + +.. code:: cpp + + enum class coefficient_hint { + row_major + }; + +Sites Hints +^^^^^^^^^^^ + +The following are supported: + + - Non-uniform. + - Uniform. + - Sorted. + +**Syntax** + +.. code:: cpp + + enum class site_hint { + non_uniform, + uniform, + sorted + }; + +Interpolation Results Hints +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Let :math:`\left\{ f_j(x) \right\}_{j=1,\dots,ny}` be a vector-valued function, +:math:`\left\{ s_i \right\}_{i=1,\dots,ns}` are sites, ``d`` is a number of derivatives (including interpolation values) that needs to be calculated. +So, size of memory to store interpolation results is ``nsite * ny * d`` elements. + +6 different layouts are possible: + + - functions-sites-derivatives + + Let :math:`\left\{ r_{j,i,k} \right\}_{j=1,\dots,ny, i=1,\dots,nsite, k=1,\dots,d}` + be an interpolation result that corresponds to the ``i-th`` site, + the ``j-th`` function, the ``k-th`` derivative. + + - functions-derivatives-sites + + Let :math:`\left\{ r_{j,k,i} \right\}_{j=1,\dots,ny, k=1,\dots,d, i=1,\dots,nsite}` + be an interpolation result that corresponds to the ``i-th`` site, + the ``j-th`` function, the ``k-th`` derivative. + + - sites-functions-derivatives + + Let :math:`\left\{ r_{i,j,k} \right\}_{i=1,\dots,nsite, j=1,\dots,ny, k=1,\dots,d}` + be an interpolation result that corresponds to the ``i-th`` site, + the ``j-th`` function, the ``k-th`` derivative. + + - sites-derivatives-functions + + Let :math:`\left\{ r_{i,k,j} \right\}_{i=1,\dots,nsite, k=1,\dots,d, j=1,\dots,ny}` + be an interpolation result that corresponds to the ``i-th`` site, + the ``j-th`` function, the ``k-th`` derivative. + + - derivatives-functions-sites + + Let :math:`\left\{ r_{k,j,i} \right\}_{k=1,\dots,d, j=1,\dots,ny, i=1,\dots,nsite}` + be an interpolation result that corresponds to the ``i-th`` site, + the ``j-th`` function, the ``k-th`` derivative. + + - derivatives-sites-functions + + Let :math:`\left\{ r_{k,i,j} \right\}_{k=1,\dots,d, i=1,\dots,nsite, j=1,\dots,ny}` + be an interpolation result that corresponds to the ``i-th`` site, + the ``j-th`` function, the ``k-th`` derivative. + + +The following are supported: + + - functions-sites-derivatives + - functions-derivatives-sites + - sites-functions-derivatives + - sites-derivatives-functions + +**Syntax** + +.. code:: cpp + + enum class interpolate_hint { + funcs_sites_ders, + funcs_ders_sites, + sites_funcs_ders, + sites_ders_funcs + }; + +Derivatives Hints +^^^^^^^^^^^^^^^^^ + +Following hints are added to choose which derivtive orders +need to be computed during the ``interpolate`` function: + + - just compute interpolation values + - compute first derivative of the spline polynomial only + - compute second derivative of the spline polynomial only + - compute third derivative of the spline polynomial only + +**Syntax** + +.. code:: cpp + + enum class derivatives { + zero, + first, + second, + third + }; + +``operator|`` is overloaded to create combinations of derivative orders +to be computed by ``interpolate``. + +**Example** + +Assume that interpolation values, 1-st and 3-rd derivatives need to be computed. +To create a bit mask that is passed to ``interpolate`` it needs following: + +.. code:: cpp + + std::bitset<32> bit_mask = derivatives::zero | derivatives::first | derivatives::third; + +Boundary Condition Types +------------------------ + +Some type of splines requires boundary conditions to be set. +The following types are supported: + + - Free end (:math:`f^{(2)}(x_1) = f^{(2)}(x_n) = 0`). + - Not-a-knot. + - Periodic. + - First derivative. + - Second Derivative. + +**Syntax** + +.. code:: cpp + + enum class bc_type { + free_end, + not_a_knot, + first_left_der, + first_right_der, + second_left_der, + second_right_der, + periodic + }; + +.. note:: + + #. First derivative and second derivative types + must be set on the left and on the right borders. + #. Free end doesn't require any values to be set. diff --git a/source/elements/oneMKL/source/domains/domains.rst b/source/elements/oneMKL/source/domains/domains.rst index 1a4f04c337..c98ca19f62 100644 --- a/source/elements/oneMKL/source/domains/domains.rst +++ b/source/elements/oneMKL/source/domains/domains.rst @@ -15,4 +15,5 @@ This section describes the Data Parallel C++ (DPC++) interface. .. include:: rng/random_number_generators.inc.rst .. include:: stats/stats.inc.rst .. include:: vm/vector_math.inc.rst +.. include:: data_fitting/data-fitting.inc.rst diff --git a/source/elements/oneMKL/source/index.rst b/source/elements/oneMKL/source/index.rst index 2ca635aa05..840cb45759 100644 --- a/source/elements/oneMKL/source/index.rst +++ b/source/elements/oneMKL/source/index.rst @@ -8,7 +8,7 @@ oneMKL ====== -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 |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, vector math and data fitting. The general assumptions, design features and requirements for the oneMKL library and host-to-device computational routines will be described in :ref:`onemkl_architecture`.