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 are:

  • Python 3.8-3.11

  • Pip

  • Cmake 3.13.x (or later)

  • C compiler

  • C++ compiler

  • GNU Make > 4.0

  • git

  • git-lfs

Note

GCC 5-9, 11, and 12 is recommended. There are known bugs with GCC 10.

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.

GPU Support#

The machine-learning backends have additional requirements in order to use GPUs for inference

Be sure to reference the installation notes for helpful information regarding various system types before installation.

Supported Versions#

Supported System for Pre-built Wheels#

Platform

CPU

GPU

Python Versions

MacOS

x86_64, aarch64

Not supported

3.8 - 3.11

Linux

x86_64

Nvidia

3.8 - 3.11

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.

Native support for various machine learning libraries and their versions is dictated by our dependency on RedisAI 1.2.7.

RedisAI

PyTorch

Tensorflow

ONNX Runtime

1.2.7 (default)

2.0.1

2.13.1

1.16.3

Warning

On Apple Silicon, only the PyTorch backend is supported for now. Please contact us if you need support for other backends

TensorFlow 2.0 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

If you would like SmartSim to also install python machine learning libraries that can be used outside SmartSim to build SmartSim-compatible models, you can request their installation through the [ml] optional dependencies, as follows:

# For bash
pip install smartsim[ml]
# For zsh
pip install smartsim\[ml\]

At this point, SmartSim is installed and can be used for more basic features. If you want to use the machine learning features of SmartSim, you will need to install the ML backends in the section below.

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

CPU Install#

To install the default ML backends for CPU, run

# run one of the following
smart build --device cpu          # install PT and TF for cpu
smart build --device cpu --onnx   # install all backends (PT, TF, ONNX) on cpu

By default, smart will install PyTorch and TensorFlow backends for use in SmartSim.

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.

GPU Install#

With the proper environment setup (see GPU Support) the only difference to building SmartSim with GPU support is to specify a different device

# run one of the following
smart build --device gpu          # install PT and TF for gpu
smart build --device gpu --onnx   # install all backends (PT, TF, ONNX) on gpu

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.

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.8 - 3.11

Linux

3.8 - 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)#

Clone the SmartRedis repository and optionally checkout a specific branch or tag:

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

The release tarball can also be used instead of cloning the git repository, but the preferred method is a repository clone.

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 unconditionally 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

The SmartRedis library will be installed in SmartRedis/install/lib/ and the SmartRedis header files (and optionally the Fortran .mod files) will be installed in SmartRedis/install/include/. The library installation can be used to easily include SmartRedis capabilities in C++, C, and Fortran applications.

The above command will build SmartRedis with the system’s default compilers. To specify a specific compler users can set the CC, CXX, and FC variables.

# 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

Customizing the library build#

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 easily with the command:

cd SmartRedis
# Static build
make lib SR_LINK=Static
# Shared build
make lib SR_LINK=Shared #or skip the SR_LINK variable as this is the default

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 SR_BUILD=Release #or skip the SR_BUILD variable as this is the default
# Debug build
make lib SR_BUILD=Debug
# Code coverage build
make lib SR_BUILD=Coverage

The name of the library produced for a Debug mode build is smartredis-debug. The name of the library produced for a Coverage mode build is smartredis-coverage. The name of the library produced for a Release mode build is smartredis. In each case, the file extension is dependent on the link type, .so or .a. All libraries will be located in the install/lib folder.

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 SR_PYTHON=ON
# Build support for Fortran
make lib SR_FORTRAN=ON # equivalent to make lib-with-fortran
# Build support for Python and Fortran
make lib SR_PYTHON=ON SR_FORTRAN=ON # or make lib-with-fortran SR_PYTHON=ON

The build mode, link type, and Fortran/Python support settings are fully orthogonal; any combination of them is supported. For example, a statically linked debug build with Python support may be achieved via the following command:

cd SmartRedis
make lib SR_LINK=Static SR_BUILD=Debug SR_PYTHON=ON

The SR_LINK, SR_BUILD, SR_PYTHON, and SR_FORTRAN variables are fully supported for all test and build targets in the Makefile.

Fortran support is built in a secondary library. The name of the Fortran library produced for a Debug mode build is smartredis-fortran-debug. The name of the library produced for a Coverage mode build is smartredis-fortran-coverage. The name of the library produced for a Release mode build is smartredis-fortran. As with the main libray, 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

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 SR_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. For debug or coverage builds, use the appropriate alternate libraries as described previously.

Linking instructions for CMake-based build systems#

The CMake instructions below illustrate how to compile a C or C++ application with SmartRedis. To build a Fortran client, uncomment out the lines after the Fortran-only comments

cmake_minimum_required(VERSION 3.13)
project(Example)

set(CMAKE_CXX_STANDARD 17)

set(SMARTREDIS_INSTALL_PATH /path/to/smartredis/install)
find_library(SMARTREDIS_LIBRARY smartredis
             PATHS ${SMARTREDIS_INSTALL_PATH}/lib
             NO_DEFAULT_PATH REQUIRED
)

# Fortran-only:
#find_library(SMARTREDIS_FORTRAN_LIBRARY smartredis-fortran
#             PATHS SMARTREDIS_INSTALL_PATH/lib
#             NO_DEFAULT_PATH REQUIRED
#)

include_directories(SYSTEM
    /usr/local/include
    ${SMARTREDIS_INSTALL_PATH}/include
)

# Build executables

add_executable(example
    example.cpp
)
target_link_libraries(example
    ${SMARTREDIS_LIBRARY}
    # Fortran-only:
    #${SMARTREDIS_FORTRAN_LIBRARY}
)

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,ml]    # for bash users
pip install -e .\[dev,ml\]  # for zsh users

Use the now installed smart cli to install the machine learning runtimes.

# run one of the following
smart build --device cpu --onnx  # install with cpu-only support
smart build --device gpu --onnx  # install with both cpu and gpu support

Build the SmartRedis library#

Clone the SmartRedis repository and optionally checkout a specific branch or tag:

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

The release tarball can also be used instead of cloning the git repository, but the preferred method is a repository clone.

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 unconditionally 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

The SmartRedis library will be installed in SmartRedis/install/lib/ and the SmartRedis header files (and optionally the Fortran .mod files) will be installed in SmartRedis/install/include/. The library installation can be used to easily include SmartRedis capabilities in C++, C, and Fortran applications.

The above command will build SmartRedis with the system’s default compilers. To specify a specific compler users can set the CC, CXX, and FC variables.

# 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

Customizing the library build#

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 easily with the command:

cd SmartRedis
# Static build
make lib SR_LINK=Static
# Shared build
make lib SR_LINK=Shared #or skip the SR_LINK variable as this is the default

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 SR_BUILD=Release #or skip the SR_BUILD variable as this is the default
# Debug build
make lib SR_BUILD=Debug
# Code coverage build
make lib SR_BUILD=Coverage

The name of the library produced for a Debug mode build is smartredis-debug. The name of the library produced for a Coverage mode build is smartredis-coverage. The name of the library produced for a Release mode build is smartredis. In each case, the file extension is dependent on the link type, .so or .a. All libraries will be located in the install/lib folder.

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 SR_PYTHON=ON
# Build support for Fortran
make lib SR_FORTRAN=ON # equivalent to make lib-with-fortran
# Build support for Python and Fortran
make lib SR_PYTHON=ON SR_FORTRAN=ON # or make lib-with-fortran SR_PYTHON=ON

The build mode, link type, and Fortran/Python support settings are fully orthogonal; any combination of them is supported. For example, a statically linked debug build with Python support may be achieved via the following command:

cd SmartRedis
make lib SR_LINK=Static SR_BUILD=Debug SR_PYTHON=ON

The SR_LINK, SR_BUILD, SR_PYTHON, and SR_FORTRAN variables are fully supported for all test and build targets in the Makefile.

Fortran support is built in a secondary library. The name of the Fortran library produced for a Debug mode build is smartredis-fortran-debug. The name of the library produced for a Coverage mode build is smartredis-fortran-coverage. The name of the library produced for a Release mode build is smartredis-fortran. As with the main libray, 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

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 SR_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. For debug or coverage builds, use the appropriate alternate libraries as described previously.

Linking instructions for CMake-based build systems#

The CMake instructions below illustrate how to compile a C or C++ application with SmartRedis. To build a Fortran client, uncomment out the lines after the Fortran-only comments

cmake_minimum_required(VERSION 3.13)
project(Example)

set(CMAKE_CXX_STANDARD 17)

set(SMARTREDIS_INSTALL_PATH /path/to/smartredis/install)
find_library(SMARTREDIS_LIBRARY smartredis
             PATHS ${SMARTREDIS_INSTALL_PATH}/lib
             NO_DEFAULT_PATH REQUIRED
)

# Fortran-only:
#find_library(SMARTREDIS_FORTRAN_LIBRARY smartredis-fortran
#             PATHS SMARTREDIS_INSTALL_PATH/lib
#             NO_DEFAULT_PATH REQUIRED
#)

include_directories(SYSTEM
    /usr/local/include
    ${SMARTREDIS_INSTALL_PATH}/include
)

# Build executables

add_executable(example
    example.cpp
)
target_link_libraries(example
    ${SMARTREDIS_LIBRARY}
    # Fortran-only:
    #${SMARTREDIS_FORTRAN_LIBRARY}
)