oneMath

https://uxlfoundation.github.io/oneMath/
Admin
oneMath is an open-source library that provides fundamental mathematical routines for...
Tokens:790,593
Snippets:2,988
Trust Score:9.7
Update:6 days ago
Show doc for...
Tokens:
Raw
### Common Linux build command for oneMath with CMake

Source: https://uxlfoundation.github.io/oneMath/building_the_project_with_dpcpp.html

Use this command sequence inside the oneMath source directory to configure, build, and install the library on Linux. Set $CXX_COMPILER and $C_COMPILER to icpx/icx for Intel oneAPI DPC++ or clang++/clang for Open DPC++. Backends are enabled via -DENABLE_<BACKEND_NAME>_BACKEND=True; MKLCPU and MKLGPU are enabled by default. Building tests and examples can be disabled with -DBUILD_FUNCTIONAL_TESTS=False and -DBUILD_EXAMPLES=False.

```bash
# Inside <path to onemath>
mkdir build && cd build
cmake .. -DCMAKE_CXX_COMPILER=$CXX_COMPILER    \ # Should be icpx or clang++
        -DCMAKE_C_COMPILER=$C_COMPILER         \ # Should be icx or clang
        -DENABLE_MKLCPU_BACKEND=False          \ # Optional: The MKLCPU backend is True by default.
        -DENABLE_MKLGPU_BACKEND=False          \ # Optional: The MKLGPU backend is True by default.
        -DENABLE_<BACKEND_NAME>_BACKEND=True   \ # Enable any other backend(s) (optional)
        -DENABLE_<BACKEND_NAME_2>_BACKEND=True \ # Multiple backends can be enabled at once.
        -DBUILD_FUNCTIONAL_TESTS=False         \ # See page *Building and Running Tests* for more on building tests. True by default.
        -DBUILD_EXAMPLES=False                   # Optional: True by default.
cmake --build .
cmake --install . --prefix <path_to_install_dir>  # required to have full package structure

```

--------------------------------

### Build oneMath on Windows with CMake and Ninja

Source: https://uxlfoundation.github.io/oneMath/building_the_project_with_dpcpp.html

Commands to configure, build, test, and install oneMath on Windows. Requires Ninja and optionally specifies the Intel compiler (icx) and dependency roots (MKL, reference BLAS/LAPACK) if not found in the environment. The install step is required to have the full package structure.

```bash
# Inside <path to onemath>
md build && cd build
cmake .. -G Ninja [-DCMAKE_CXX_COMPILER=<path_to_icx_compiler>\bin\icx] # required only if icx is not found in environment variable PATH
                  [-DCMAKE_C_COMPILER=<path_to_icx_compiler>\bin\icx]   # required only if icx is not found in environment variable PATH
                  [-DMKL_ROOT=<mkl_install_prefix>]                     # required only if environment variable MKLROOT is not set
                  [-DREF_BLAS_ROOT=<reference_blas_install_prefix>]     # required only for testing
                  [-DREF_LAPACK_ROOT=<reference_lapack_install_prefix>] # required only for testing
ninja
ctest
cmake --install . --prefix <path_to_install_dir> # required to have full package structure

```

--------------------------------

### Using find_package to link against installed oneMath

Source: https://uxlfoundation.github.io/oneMath/using_onemath_with_cmake.html

Use this snippet to consume a previously installed oneMath library. The compiler used for the target library or application should match that used to build oneMath. Link against the ONEMATH::onemath target for the entire library with run-time dispatching.

```cmake
find_package(oneMath REQUIRED)
target_link_libraries(myTarget PRIVATE ONEMATH::onemath)
```

--------------------------------

### skip_ahead Example with Partitioned Number of Elements

Source: https://uxlfoundation.github.io/oneMath/spec/domains/rng/host_api/onemath-rng-skip_ahead.html

Creates an engine and skips ahead by 2^64 elements using a partitioned num_to_skip list.

```cpp
// Creating the first engine
oneapi::math::rng::mrg32k3a engine_1(queue, seed);

// To skip 2^64 elements in the random stream number of skipped elements should be
// represented as num_to_skip = 2^64 = 0 + 1 * 2^64
std::initializer_list<std::uint64_t> num_to_skip = {0, 1};

// Creating the 2nd engine based on 1st. Skipping by 2^64
oneapi::math::rng::mrg32k3a engine_2(engine_1);
oneapi::math::rng::skip_ahead(engine_2, num_to_skip);
```

--------------------------------

### Build Reference LAPACK Libraries

Source: https://uxlfoundation.github.io/oneMath/building_and_running_tests.html

Builds a reference LAPACK implementation (including BLAS) with both 32-bit and 64-bit indexing. Requires shared libraries supporting both indexing modes. Install to ~/lapack and then set -DREF_BLAS_ROOT and -DREF_LAPACK_ROOT to the install path.

```bash
git clone https://github.com/Reference-LAPACK/lapack.git
cd lapack; mkdir -p build; cd build
cmake -DCMAKE_INSTALL_PREFIX=~/lapack -DCBLAS=True -DLAPACK=True -DLAPACKE=True -DBUILD_INDEX64=True -DBUILD_SHARED_LIBS=True ..
cmake --build . -j --target install
cmake -DCMAKE_INSTALL_PREFIX=~/lapack -DCBLAS=True -DLAPACK=True -DLAPACKE=True -DBUILD_INDEX64=False -DBUILD_SHARED_LIBS=True ..
cmake --build . -j --target install
```

--------------------------------

### Header file declaration for newlib asum

Source: https://uxlfoundation.github.io/oneMath/create_new_backend.html

Example header file include/oneapi/math/blas/detail/newlib/onemath_blas_newlib.hpp declaring the entry point to the newlib wrapper for the asum operation.

```cpp
namespace oneapi {
namespace math {
namespace newlib {

void asum(sycl::queue &queue, std::int64_t n, sycl::buffer<float, 1> &x, std::int64_t incx,
          sycl::buffer<float, 1> &result);

```

--------------------------------

### skip_ahead Example

Source: https://uxlfoundation.github.io/oneMath/spec/domains/rng/host_api/onemath-rng-skip_ahead.html

Creates three identical engines and skips ahead by 7 and 14 elements for the second and third engines respectively.

```cpp
// Creating 3 identical engines
oneapi::math::rng::mcg31m1 engine_1(queue, seed);
oneapi::math::rng::mcg31m1 engine_2(engine_1);
oneapi::math::rng::mcg31m1 engine_3(engine_2);

// Skipping ahead by 7 elements the 2nd engine
oneapi::math::rng::skip_ahead(engine_2, 7);

// Skipping ahead by 14 elements the 3rd engine
oneapi::math::rng::skip_ahead(engine_3, 14);
```

--------------------------------

### Build oneMath with AdaptiveCpp using CMake

Source: https://uxlfoundation.github.io/oneMath/building_the_project_with_adaptivecpp.html

Run these commands from the project root to configure, build, and install oneMath with AdaptiveCpp. Set the compiler and enable desired backends via CMake options; MKLGPU must be disabled. ACPP_TARGETS sets target architectures, defaulting to 'generic' if not specified. BUILD_FUNCTIONAL_TESTS and BUILD_EXAMPLES are True by default and can be disabled.

```bash
# Inside <path to onemath>
mkdir build && cd build
cmake .. -DONEMATH_SYCL_IMPLEMENTATION=adaptivecpp \ # Indicate that AdaptiveCpp is being used.
        -DENABLE_MKLGPU_BACKEND=False              \ # MKLGPU backend is not supported by AdaptiveCpp
        -DENABLE_<BACKEND_NAME>_BACKEND=True       \ # Enable backend(s) (optional)
        -DENABLE_<BACKEND_NAME_2>_BACKEND=True     \ # Multiple backends can be enabled at once.
        -DACPP_TARGETS=omp\;hip:gfx90a,gfx906      \ # Set target architectures depending on supported devices.
        -DBUILD_FUNCTIONAL_TESTS=False             \ # See section *Building the tests* for more on building tests. True by default.
        -DBUILD_EXAMPLES=False                     # Optional: True by default.
cmake --build .
cmake --install . --prefix <path_to_install_dir> # required to have full package structure

```

--------------------------------

### get_value(config_param, real_scalar_t*)

Source: https://uxlfoundation.github.io/oneMath/spec/domains/dft/descriptor.html

Gets a configuration parameter value into a real_scalar_t pointer.

```APIDOC
## void get_value(config_param param, real_scalar_t* value_ptr) const

### Description
Gets the value of the configuration parameter specified by `param` and stores it in the memory pointed to by `value_ptr`.

### Syntax
```cpp
void get_value(config_param param, real_scalar_t* value_ptr) const;
```

### Parameters
- `param` (config_param) - Required - The configuration parameter to query.
- `value_ptr` (real_scalar_t*) - Required - Pointer to where the value will be stored.

### Returns
None.

```

--------------------------------

### get_value(config_param, precision*)

Source: https://uxlfoundation.github.io/oneMath/spec/domains/dft/descriptor.html

Gets a configuration parameter value into a precision pointer.

```APIDOC
## void get_value(config_param param, precision* value_ptr) const

### Description
Gets the value of the configuration parameter specified by `param` and stores it in the memory pointed to by `value_ptr`.

### Syntax
```cpp
void get_value(config_param param, precision* value_ptr) const;
```

### Parameters
- `param` (config_param) - Required - The configuration parameter to query.
- `value_ptr` (precision*) - Required - Pointer to where the value will be stored.

### Returns
None.

```

--------------------------------

### Using FetchContent to build oneMath from source

Source: https://uxlfoundation.github.io/oneMath/using_onemath_with_cmake.html

Use this snippet to have CMake automatically download and build oneMath as part of your project. Set build parameters before FetchContent_Declare. Link against the 'onemath' target for run-time dispatching, or 'onemath_<domain>_<backend>' for compile-time dispatching.

```cmake
include(FetchContent)
set(BUILD_FUNCTIONAL_TESTS False)
set(BUILD_EXAMPLES False)
set(ENABLE_<BACKEND_NAME>_BACKEND True)
FetchContent_Declare(
        onemath_library
        GIT_REPOSITORY https://github.com/uxlfoundation/oneMath.git
        GIT_TAG develop
)
FetchContent_MakeAvailable(onemath_library)

target_link_libraries(myTarget PRIVATE onemath)
```

--------------------------------

### get_value(config_param, domain*)

Source: https://uxlfoundation.github.io/oneMath/spec/domains/dft/descriptor.html

Gets a configuration parameter value into a domain pointer.

```APIDOC
## void get_value(config_param param, domain* value_ptr) const

### Description
Gets the value of the configuration parameter specified by `param` and stores it in the memory pointed to by `value_ptr`.

### Syntax
```cpp
void get_value(config_param param, domain* value_ptr) const;
```

### Parameters
- `param` (config_param) - Required - The configuration parameter to query.
- `value_ptr` (domain*) - Required - Pointer to where the value will be stored.

### Returns
None.

```

--------------------------------

### Buffer-based example with philox4x32x10 and gaussian distribution

Source: https://uxlfoundation.github.io/oneMath/spec/domains/rng/host_api/onemath-rng-usage-model.html

Shows the minimal usage of oneMath RNG with SYCL buffers. Creates a philox4x32x10 engine and a gaussian<double> distribution, then calls generate to fill a SYCL buffer. The seed and n variables are not defined in the snippet.

```cpp
#include "oneapi/math/rng.hpp"

int main() {
    sycl::queue q;

    // Create the random number generator object
    oneapi::math::rng::philox4x32x10 engine(q, seed);
    // Create the distribution object
    oneapi::math::rng::gaussian<double> distr(5.0, 2.0);
    // Fill the SYCL buffer with random numbers
    oneapi::math::rng::generate(distr, engine, n, sycl_buffer);

    // ...

}

```

--------------------------------

### get_value(config_param, config_value*)

Source: https://uxlfoundation.github.io/oneMath/spec/domains/dft/descriptor.html

Gets a configuration parameter value into a config_value pointer.

```APIDOC
## void get_value(config_param param, config_value* value_ptr) const

### Description
Gets the value of the configuration parameter specified by `param` and stores it in the memory pointed to by `value_ptr`.

### Syntax
```cpp
void get_value(config_param param, config_value* value_ptr) const;
```

### Parameters
- `param` (config_param) - Required - The configuration parameter to query.
- `value_ptr` (config_value*) - Required - Pointer to where the value will be stored.

### Returns
None.

```

--------------------------------

### weibull::a() const - Get Displacement Value

Source: https://uxlfoundation.github.io/oneMath/spec/domains/rng/host_api/onemath-rng-weibull.html

Returns the distribution parameter a - the displacement value.

```APIDOC
## weibull::a() const

### Description
Returns the distribution parameter a - the displacement value.

### Syntax
```cpp
RealType a() const;
```

### Parameters
None.

### Return Value
Returns the distribution parameter a - displacement value.
```

--------------------------------

### USM-based example: compute mean with oneMath Summary Statistics

Source: https://uxlfoundation.github.io/oneMath/spec/domains/stats/onemath_stats_usage_model.html

Shows the typical usage model for oneMath Summary Statistics: create a dataset with make_dataset<oneapi::math::stats::layout::row_major> and call oneapi::math::stats::mean on a SYCL queue. The dataset and mean output are expected to be allocated in Unified Shared Memory (USM) before the calls; the returned event is waited on to ensure completion.

```cpp
#include "oneapi/math/stats.hpp"

int main() {
    sycl::queue queue;

    constexpr std::size_t n_observations = 1000;
    constexpr std::size_t n_dims = 3;

    // allocate Unified Shared Memory for the dataset of the size n_observations * n_dims and fill it with any data
    // allocate Unified Shared Memory for the mean output of the size n_dims

    // create oneapi::math::stats::dataset
    auto dataset = oneapi::math::stats::make_dataset<oneapi::math::stats::layout::row_major>(n_dims, n_observations, dataset_ptr);

    // call statistics computation routine
    auto event = oneapi::math::stats::mean(queue, dataset, mean_ptr);

    // wait until computations are completed
    event.wait();

    // ...
}

```

--------------------------------

### get_value(config_param, std::int64_t*)

Source: https://uxlfoundation.github.io/oneMath/spec/domains/dft/descriptor.html

Gets a configuration parameter value into a std::int64_t pointer.

```APIDOC
## void get_value(config_param param, std::int64_t* value_ptr) const

### Description
Gets the value of the configuration parameter specified by `param` and stores it in the memory pointed to by `value_ptr`.

### Syntax
```cpp
void get_value(config_param param, std::int64_t* value_ptr) const;
```

### Parameters
- `param` (config_param) - Required - The configuration parameter to query.
- `value_ptr` (std::int64_t*) - Required - Pointer to where the value will be stored.

### Returns
None.

```

--------------------------------

### Link newlib backend in tests/unit_tests/CMakeLists.txt

Source: https://uxlfoundation.github.io/oneMath/create_new_backend.html

Adds instructions to link unit tests with the new backend library. The plus signs indicate the lines to add.

```cmake
   if(ENABLE_MKLCPU_BACKEND)
       add_dependencies(test_main_ct onemath_blas_mklcpu)
       if(BUILD_SHARED_LIBS)
           list(APPEND ONEMATH_LIBRARIES onemath_blas_mklcpu)
       else()
           list(APPEND ONEMATH_LIBRARIES -foffload-static-lib=${CMAKE_LIBRARY_OUTPUT_DIRECTORY}/libonemath_blas_mklcpu.a)
           find_package(MKL REQUIRED)
           list(APPEND ONEMATH_LIBRARIES ${MKL_LINK_C})
       endif()
   endif()
+
+    if(ENABLE_NEWLIB_BACKEND)
+       add_dependencies(test_main_ct onemath_blas_newlib)
+       if(BUILD_SHARED_LIBS)
+           list(APPEND ONEMATH_LIBRARIES onemath_blas_newlib)
+       else()
+           list(APPEND ONEMATH_LIBRARIES -foffload-static-lib=${CMAKE_LIBRARY_OUTPUT_DIRECTORY}/libonemath_blas_newlib.a)
+           find_package(NEWLIB REQUIRED)
+           list(APPEND ONEMATH_LIBRARIES ONEMATH::NEWLIB::NEWLIB)
+       endif()
+   endif()

```
Tokens:
Raw