Basic Installation

Basic Installation#

The following will show how to install both SmartSim and SmartRedis.

Note

For users on platforms with a ‘site install’ of SmartSim please follow Site Installation.

Prerequisites#

Basic#

The base prerequisites to install SmartSim and SmartRedis wtih CPU-only support are:

  • Python 3.9-3.11

  • Pip

  • Cmake 3.13.x (or later)

  • C compiler

  • C++ compiler

  • GNU Make > 4.0

  • git

Note

GCC 9, 11-13 is recommended (here are known issues compiling with GCC 10). For CUDA 11.8, GCC 9 or 11 must be used.

Warning

Apple Clang 15 seems to have issues on MacOS with Apple Silicon. Please modify your path to ensure that a version of GCC installed by brew has priority. Note this seems to be hardcoded to gcc and g++ in the Redis build so ensure that which gcc g++ do not point to Apple Clang.

ML Library Support#

We currently support both Nvidia and AMD GPUs when using RedisAI for GPU inference. The support for these GPUs often depends on the version of the CUDA or ROCm stack that is availble on your machine. In _most_ cases, the versions backwards compatible. If you encounter problems, please contact us and we can build the backend libraries for your desired version of CUDA and ROCm.

CPU backends are provided for Apple (both Intel and Apple Silicon) and Linux (x86_64).

Be sure to reference the table below to find which versions of the ML libraries are supported for your particular platform. Additional, see installation notes for helpful information regarding various system types before installation.

Linux#

Additional requirements:

  • GCC <= 11

  • CUDA Toolkit 11.7 or 11.8

  • cuDNN 8.9

Nvidia CUDA 11#

Python Versions

Torch

Tensorflow

ONNX Runtime

3.9-3.11

2.3.1

2.14.1

1.17.3

MacOSX#

Apple Silicon ARM64 (no Metal support)#

Python Versions

Torch

Tensorflow

ONNX Runtime

3.9-3.11

2.4.0

2.17

1.17.3

Note

Users have succesfully run SmartSim on Windows using Windows Subsystem for Linux with Nvidia support. Generally, users should follow the Linux instructions here, however we make no guarantee or offer of support.

TensorFlow and Keras are supported through graph freezing.

ScikitLearn and Spark models are supported by SmartSim as well through the use of the ONNX runtime (which is not built by default due to issues with glibc on a variety of Linux platforms).

MacOS-only#

We recommend users and contributors install brew for managing installed packages. For contributors, the following brew packages can be helpful:

  • openmpi for building and running parallel SmartRedis examples

  • doxygen for building the documentation

  • cmake for building SmartSim and SmartRedis from source

For Mac OS users, the version of make that comes with the Mac command line tools is often 3.81 which needs to be updated to install SmartSim. Users can run brew install make to get make > 4.0 but brew will install it as gmake. An easy way around this is to run alias make=gmake.

SmartSim#

There are two stages for the installation of SmartSim.

  1. pip install SmartSim Python package

  2. Build SmartSim using the smart command line tool

Step 1: Install Python Package#

We first recommend creating a new virtual environment:

python -m venv /path/to/new/environment
source /path/to/new/environment/bin/activate

and install SmartSim from PyPI with the following command:

pip install smartsim

At this point, SmartSim can be used for describing and launching experiments, but without any database/feature store functionality which allows for ML-enabled workflows.

Step 2: Build SmartSim#

Use the smart cli tool to install the machine learning backends that are built into the Orchestrator database. smart is installed during the pip installation of SmartSim and may only be available while your virtual environment is active.

To see all the installation options:

smart --help

# run one of the following
smart build --device cpu      # For unaccelerated AI/ML loads
smart build --device cuda118  # Nvidia Accelerator with CUDA 11.8
smart build --device cuda125  # Nvidia Accelerator with CUDA 12.5
smart build --device rocm57   # AMD Accelerator with ROCm 5.7.0

By default, smart will install all backends available for the specified accelerator _and_ the compatible versions of the Python packages associated with the backends. To disable support for a specific backend, smart build accepts the flags --skip-torch, --skip-tensorflow, --skip-onnx which can also be used in combination.

Note

If a re-build is needed for any reason, smart clean will remove all of the previous installs for the ML backends and smart clobber will remove all pre-built dependencies as well as the ML backends.

Note

GPU builds can be troublesome due to the way that RedisAI and the ML-package backends look for the CUDA Toolkit and cuDNN libraries. Please see the Platform Installation Section section for guidance.

Dragon Install#

Dragon is an HPC-native library for distributed computing. SmartSim can use Dragon as a launcher on systems with Slurm or PBS as schedulers. To install the correct version of Dragon, you can add the --dragon option to smart build. For example, to install dragon alongside the RedisAI CPU backends, you can run

smart build --device cpu --dragon           # install Dragon, PT and TF for cpu

Note

Dragon is only supported on Linux systems. For further information, you can read the dedicated documentation page.

SmartRedis#

There are implementations of the SmartRedis client in 4 languages: Python, C++, C, and Fortran. The Python client is installed through pip and the compiled clients can be built as a static or shared library through cmake.

SmartRedis Python supports the same architectures for pre-built wheels that SmartSim does.

Supported Systems for Pre-built Wheels#

Platform

Python Versions

MacOS

3.9 - 3.11

Linux

3.9 - 3.11

The Python client for SmartRedis is installed through pip as follows:

First, activate your Python virtual environment:

conda activate <env name>

Install SmartRedis Python client from PyPI:

pip install smartredis

Developers installing the Python client from PyPI can install the SmartRedis client with additional dependencies for testing and documentation with:

pip install smartredis[dev]
# or if using ZSH
pip install smartredis\[dev\]

Now, when inside your virtual environment, you should be able to import the Client from smartredis as follows:

python -c 'from smartredis import Client'

Build SmartRedis Library (C++, C, Fortran)#

For C, C++, and Fortran applications, the SmartRedis client library will need to be compiled and linked in. The build system is CMake-based but we also offer a Makefile that cover the requirements for most users.

Downloading SmartRedis via the Github release page is possible, however we recommend that most users clone the repository via git

git clone https://github.com/CrayLabs/SmartRedis.git [--branch tag_name] smartredis

CMake-based build#

The CMakeLists.txt file in the SmartRedis root directory is fully self contained and can be used directly to compile and install the SmartRedis library. At a bare minimum users, can compile the library with

cd /path/to/SmartRedis
mkdir build
cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/path/to/install/
make install -j

which will compile the C and C++ interfaces to SmartRedis and install the libraries and all header files to /path/to/install/location.

For other CMake-based projects, the config files for SmartRedis will be in the share/cmake/smartredis subdirectory and can be included by modifying the application’s CMakeLists.txt

find_package(smartredis REQUIRED)
target_link_libraries(example_target smartredis)
target_include_directories(example_target ${smartredis_INCLUDE_DIR})

For more advanced used we provide the following options, their default settings, and the allowed values which can be set at configuration time via -DEXAMPLE_PARAMETER=EXAMPLE_VALUE

SmartRedis CMake options#

Parameter name

Default

Allowed values

Description

BUILD_FORTRAN

OFF

ON, OFF

Build the Fortran client library in addition to C/C++

BUILD_PYTHON

OFF

ON, OFF

Build the Python client in addition to C/C++ (useful if the SmartRedis python package was installed in editable mode)

BUILD_SHARED_LIBS

ON

ON, OFF

If ON, build SmartRedis libraries as a dynamic library, otherwise as a static library

CMAKE_BUILD_TYPE

Release

Release, Debug, Coverage

Determine whether the optimized, debuggable, or debuggable with coverage version of SmartRedis will be compiled

CMAKE_INSTALL_PREFIX

/usr/local

Any path

Install path prefix, prepended onto install directories.

PEDANTIC

OFF

ON, OFF

If ON, error out if any compiler warnings are found

RETAIN_RPATH

ON

ON, OFF

If ON, retain the path to the libsmartredis library for the Fortran library when using dynamic linking

Makefile-based build#

The `Makefile included in the top level of the SmartRedis repository has two main targets: lib which will create a dynamic library for C, C++, and (optionally) Fortran and Python clients; and lib-with-fortran which will also build a library for Fortran applications. make help will list additional targets that are used for SmartRedis development.

cd SmartRedis
make lib #or lib-with-fortran

By default, the SmartRedis library will be compiled as a shared library with the system default compilers and installed in SmartRedis/install/lib/ and the SmartRedis header files (and optionally the Fortran .mod files) will be installed in SmartRedis/install/include/.

# GCC Toolchain
make lib-with-fortran CC=foo CXX=bar FC=baz

For reference, the appropriate values for CC, CXX, and FC for the compiler chains we support are:

Values for compiler chains#

Compiler Chain

CC

CXX

FC

GCC

gcc

g++

gfortran

Intel (Classic)

icc

icpc

ifort

Intel (OneAPI)

icx

icpx

ifx

NVHPC

nvc

nvc++

nvfortran

By default, the SmartRedis library is built as a shared library. For some applications, however, it is preferable to link to a statically compiled library. This can be done by specifying the LINK_TYPE

make lib LINK_TYPE=shared # Default shared
make lib LINK_TYPE=static # Static build

Linked statically, the SmartRedis library will have a .a file extension. When linked dynamically, the SmartRedis library will have a .so file extension.

It is also possible to adjust compilation settings for the SmartRedis library. By default, the library compiles in an optimized build (Release), but debug builds with full symbols (Debug) can be created as can debug builds with extensions enabled for code coverage metrics (Coverage; this build type is only available with GNU compilers). Similar to configuring a link type, selecting the build mode can be done via a variable supplied to make:

cd SmartRedis
# Release build
make lib BUILD_TYPE=Release # Default
# Debug build
make lib BUILD_TYPE=Debug
# Code coverage build
make lib BUILD_TYPE=Coverage

Finally, it is possible to build SmartRedis to include Python and/or Fortran support (both are omitted by default):

cd SmartRedis
# Build support for Python
make lib BUILD_PYTHON=ON
# Build support for Fortran
make lib BUILD_FORTRAN=ON # equivalent to make lib-with-fortran
# Build support for Python and Fortran
make lib BUILD_PYTHON=ON BUILD_FORTRAN=ON # or make lib-with-fortran BUILD_PYTHON=ON

Any combination of the build mode, link type, and Fortran/Python support settings is supported For example, a statically linked debug build with Python support may be achieved via the following command:

cd SmartRedis
make lib LINK_TYPE=Static BUILD_TYPE=Debug BUILD_PYTHON=ON

The LINK_TYPE, BUILD_TYPE, BUILD_PYTHON, and BUILD_FORTRAN variables are fully supported for all test and build targets in the Makefile.

Fortran support is built in a secondary library libsmartredis-fortran. As with the main library, the file extension is dependent on the link type, .so or .a. All libraries will be located in the install/lib folder.

Additional make variables are described in the help make target:

cd SmartRedis
make help

Adding SmartRedis as a CMake ExternalProject#

Most applications should be able to incorporate the following into their CMakeLists.txt to

include(ExternalProject)
ExternalProject_Add(smartredis
    GIT_REPOSITORY https://github.com/CrayLabs/SmartRedis.git
    CMAKE_ARGS -DCMAKE_INSTALL_PREFIX:PATH=${CMAKE_BINARY_DIR}/external
               -DBUILD_FORTRAN=on # For Fortran applications
    PREFIX ${CMAKE_BINARY_DIR}/external
)
ExternalProject_Get_Property(smartredis binary_dir source_dir)

add_library(libsmartredis SHARED IMPORTED)
add_dependencies(libsmartredis smartredis)
set_target_properties(libsmartredis PROPERTIES
    IMPORTED_LOCATION ${binary_dir}/libsmartredis.so
    INTERFACE_INCLUDE_DIRECTORIES  $<INSTALL_INTERFACE:${CMAKE_BINARY_DIR}/external/include}>
)

# Optional, only for Fortran applications
add_library(libsmartredis-fortran SHARED IMPORTED)
add_dependencies(libsmartredis-fortran smartredis)
set_target_properties(libsmartredis-fortran PROPERTIES
    IMPORTED_LOCATION ${binary_dir}/libsmartredis-fortran.so
    INTERFACE_INCLUDE_DIRECTORIES  $<INSTALL_INTERFACE:${CMAKE_BINARY_DIR}/external/include}>
)

# ... define the example_target executable here

target_include_directories(example_target PRIVATE ${CMAKE_BINARY_DIR}/external/include)
target_link_libraries(example_target libsmartredis)
# Optional, only for Fortran applcations
target_link_libraries(example_target libsmartredis-fortran)

Linking instructions using compiler flags#

For applications which use pre-defined compiler flags for compilation, the following flags should be included for the preprocessor

-I/path/to/smartredis/install/include

The linking flags will differ slightly whether the Fortran client library needs to be included. If so, be sure that you ran make lib-with-fortran (or make lib BUILD_FORTRAN=ON) and include the SmartRedis fortran library via the following flags:

-L/path/to/smartredis/install/lib -lsmartredis [-lsmartredis-fortran]

Note

Fortran applications need to link in both smartredis-fortran and smartredis libraries whereas C/C++ applications require only smartredis.

Warning

For static linking, due to limitations with CMake, users should also add the following flags -lhiredis -lredis++ to the link command

From Source#

This section will be geared towards contributors who want to install SmartSim and SmartRedis from source for development purposes. If you are installing from source for other reasons, follow the steps below but use the source distributions provided on GitHub or PyPI.

Install SmartSim from Source#

First, clone SmartSim.

git clone https://github.com/CrayLabs/SmartSim smartsim

And then install SmartSim with pip in editable mode. This way, SmartSim is installed in your virtual environment and available on sys.path, but the source remains at the site of the clone instead of in site-packages.

cd smartsim
pip install -e .[dev]       # for bash users
pip install -e ".[dev]"  # for zsh users

Use the now installed smart cli to install the machine learning runtimes and dragon. Referring to “Step 2: Build SmartSim above”.

Build the SmartRedis library#

For C, C++, and Fortran applications, the SmartRedis client library will need to be compiled and linked in. The build system is CMake-based but we also offer a Makefile that cover the requirements for most users.

Downloading SmartRedis via the Github release page is possible, however we recommend that most users clone the repository via git

git clone https://github.com/CrayLabs/SmartRedis.git [--branch tag_name] smartredis

CMake-based build#

The CMakeLists.txt file in the SmartRedis root directory is fully self contained and can be used directly to compile and install the SmartRedis library. At a bare minimum users, can compile the library with

cd /path/to/SmartRedis
mkdir build
cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/path/to/install/
make install -j

which will compile the C and C++ interfaces to SmartRedis and install the libraries and all header files to /path/to/install/location.

For other CMake-based projects, the config files for SmartRedis will be in the share/cmake/smartredis subdirectory and can be included by modifying the application’s CMakeLists.txt

find_package(smartredis REQUIRED)
target_link_libraries(example_target smartredis)
target_include_directories(example_target ${smartredis_INCLUDE_DIR})

For more advanced used we provide the following options, their default settings, and the allowed values which can be set at configuration time via -DEXAMPLE_PARAMETER=EXAMPLE_VALUE

SmartRedis CMake options#

Parameter name

Default

Allowed values

Description

BUILD_FORTRAN

OFF

ON, OFF

Build the Fortran client library in addition to C/C++

BUILD_PYTHON

OFF

ON, OFF

Build the Python client in addition to C/C++ (useful if the SmartRedis python package was installed in editable mode)

BUILD_SHARED_LIBS

ON

ON, OFF

If ON, build SmartRedis libraries as a dynamic library, otherwise as a static library

CMAKE_BUILD_TYPE

Release

Release, Debug, Coverage

Determine whether the optimized, debuggable, or debuggable with coverage version of SmartRedis will be compiled

CMAKE_INSTALL_PREFIX

/usr/local

Any path

Install path prefix, prepended onto install directories.

PEDANTIC

OFF

ON, OFF

If ON, error out if any compiler warnings are found

RETAIN_RPATH

ON

ON, OFF

If ON, retain the path to the libsmartredis library for the Fortran library when using dynamic linking

Makefile-based build#

The `Makefile included in the top level of the SmartRedis repository has two main targets: lib which will create a dynamic library for C, C++, and (optionally) Fortran and Python clients; and lib-with-fortran which will also build a library for Fortran applications. make help will list additional targets that are used for SmartRedis development.

cd SmartRedis
make lib #or lib-with-fortran

By default, the SmartRedis library will be compiled as a shared library with the system default compilers and installed in SmartRedis/install/lib/ and the SmartRedis header files (and optionally the Fortran .mod files) will be installed in SmartRedis/install/include/.

# GCC Toolchain
make lib-with-fortran CC=foo CXX=bar FC=baz

For reference, the appropriate values for CC, CXX, and FC for the compiler chains we support are:

Values for compiler chains#

Compiler Chain

CC

CXX

FC

GCC

gcc

g++

gfortran

Intel (Classic)

icc

icpc

ifort

Intel (OneAPI)

icx

icpx

ifx

NVHPC

nvc

nvc++

nvfortran

By default, the SmartRedis library is built as a shared library. For some applications, however, it is preferable to link to a statically compiled library. This can be done by specifying the LINK_TYPE

make lib LINK_TYPE=shared # Default shared
make lib LINK_TYPE=static # Static build

Linked statically, the SmartRedis library will have a .a file extension. When linked dynamically, the SmartRedis library will have a .so file extension.

It is also possible to adjust compilation settings for the SmartRedis library. By default, the library compiles in an optimized build (Release), but debug builds with full symbols (Debug) can be created as can debug builds with extensions enabled for code coverage metrics (Coverage; this build type is only available with GNU compilers). Similar to configuring a link type, selecting the build mode can be done via a variable supplied to make:

cd SmartRedis
# Release build
make lib BUILD_TYPE=Release # Default
# Debug build
make lib BUILD_TYPE=Debug
# Code coverage build
make lib BUILD_TYPE=Coverage

Finally, it is possible to build SmartRedis to include Python and/or Fortran support (both are omitted by default):

cd SmartRedis
# Build support for Python
make lib BUILD_PYTHON=ON
# Build support for Fortran
make lib BUILD_FORTRAN=ON # equivalent to make lib-with-fortran
# Build support for Python and Fortran
make lib BUILD_PYTHON=ON BUILD_FORTRAN=ON # or make lib-with-fortran BUILD_PYTHON=ON

Any combination of the build mode, link type, and Fortran/Python support settings is supported For example, a statically linked debug build with Python support may be achieved via the following command:

cd SmartRedis
make lib LINK_TYPE=Static BUILD_TYPE=Debug BUILD_PYTHON=ON

The LINK_TYPE, BUILD_TYPE, BUILD_PYTHON, and BUILD_FORTRAN variables are fully supported for all test and build targets in the Makefile.

Fortran support is built in a secondary library libsmartredis-fortran. As with the main library, the file extension is dependent on the link type, .so or .a. All libraries will be located in the install/lib folder.

Additional make variables are described in the help make target:

cd SmartRedis
make help

Adding SmartRedis as a CMake ExternalProject#

Most applications should be able to incorporate the following into their CMakeLists.txt to

include(ExternalProject)
ExternalProject_Add(smartredis
    GIT_REPOSITORY https://github.com/CrayLabs/SmartRedis.git
    CMAKE_ARGS -DCMAKE_INSTALL_PREFIX:PATH=${CMAKE_BINARY_DIR}/external
               -DBUILD_FORTRAN=on # For Fortran applications
    PREFIX ${CMAKE_BINARY_DIR}/external
)
ExternalProject_Get_Property(smartredis binary_dir source_dir)

add_library(libsmartredis SHARED IMPORTED)
add_dependencies(libsmartredis smartredis)
set_target_properties(libsmartredis PROPERTIES
    IMPORTED_LOCATION ${binary_dir}/libsmartredis.so
    INTERFACE_INCLUDE_DIRECTORIES  $<INSTALL_INTERFACE:${CMAKE_BINARY_DIR}/external/include}>
)

# Optional, only for Fortran applications
add_library(libsmartredis-fortran SHARED IMPORTED)
add_dependencies(libsmartredis-fortran smartredis)
set_target_properties(libsmartredis-fortran PROPERTIES
    IMPORTED_LOCATION ${binary_dir}/libsmartredis-fortran.so
    INTERFACE_INCLUDE_DIRECTORIES  $<INSTALL_INTERFACE:${CMAKE_BINARY_DIR}/external/include}>
)

# ... define the example_target executable here

target_include_directories(example_target PRIVATE ${CMAKE_BINARY_DIR}/external/include)
target_link_libraries(example_target libsmartredis)
# Optional, only for Fortran applcations
target_link_libraries(example_target libsmartredis-fortran)

Linking instructions using compiler flags#

For applications which use pre-defined compiler flags for compilation, the following flags should be included for the preprocessor

-I/path/to/smartredis/install/include

The linking flags will differ slightly whether the Fortran client library needs to be included. If so, be sure that you ran make lib-with-fortran (or make lib BUILD_FORTRAN=ON) and include the SmartRedis fortran library via the following flags:

-L/path/to/smartredis/install/lib -lsmartredis [-lsmartredis-fortran]

Note

Fortran applications need to link in both smartredis-fortran and smartredis libraries whereas C/C++ applications require only smartredis.

Warning

For static linking, due to limitations with CMake, users should also add the following flags -lhiredis -lredis++ to the link command

Contents