Basic Installation
Contents
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.7-3.9
Pip
Cmake 3.13.x (or later)
C compiler
C++ compiler
GNU Make > 4.0
git
Note
GCC 5-9, 11, and 12 is recommended. There are known bugs with GCC 10.
GPU Support¶
The machine-learning backends have additional requirements in order to use GPUs for inference
OS: Linux
GPU: Nvidia
Be sure to reference the installation notes for helpful information regarding various system types before installation.
Supported Versions¶
Platform |
CPU |
GPU |
Python Versions |
---|---|---|---|
MacOS |
x86_64 |
Not supported |
3.7 - 3.9 |
Linux |
x86_64 |
Nvidia |
3.7 - 3.9 |
Note
Windows is not supported and there are currently no plans to support Windows.
Native support for various machine learning libraries and their versions is dictated by our dependency on RedisAI 1.2.7. Users can also select RedisAI 1.2.3 or 1.2.5 (though that also limits the version of the ML libraries).
RedisAI |
PyTorch |
Tensorflow |
ONNX Runtime |
---|---|---|---|
1.2.7 (default) |
1.11.0 |
2.8.0 |
1.11.1 |
1.2.5 |
1.9.0 |
2.6.0 |
1.9.0 |
1.2.3 |
1.7.0 |
2.5.2 |
1.9.0 |
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 and lack of support for Mac OS X).
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 documention
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.
pip install SmartSim Python package
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 Machine Learning libraries that
can be used outside SmartSim to build SmartSim-compatible models, you
can request their installation through the ml
flag as follows:
# For bash
pip install smartsim[ml]
# or if using 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
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 gpu
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.
Platform |
Python Versions |
---|---|
MacOS |
3.7 - 3.9 |
Linux |
3.7 - 3.9 |
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 3.7.7 (default, May 7 2020, 21:25:33)
[GCC 7.3.0] :: Anaconda, Inc. on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> 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 Python
clients and lib-with-fortran
which will also additionally 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.
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
and
include the SmartRedis fortran library in the following flags
-L/path/to/smartredis/install/lib -lhiredis -lredis++ -lsmartredis [-lsmartredis-fortran]
Note
Fortran applications need to link in both smartredis-fortran
and
smartredis
libraries whereas C/C++ applications require only
smartredis
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
project(Example)
cmake_minimum_required(VERSION 3.13)
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. If you are installing from source for other reasons, follow the steps below but use the distribution provided hosted 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 in PYTHONPATH, 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 -v --device cpu # verbose install cpu
smart build -v --device gpu # verbose install gpu
smart build -v --device gpu --onnx # install all backends (PT, TF, ONNX) on gpu
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 Python
clients and lib-with-fortran
which will also additionally 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.
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
and
include the SmartRedis fortran library in the following flags
-L/path/to/smartredis/install/lib -lhiredis -lredis++ -lsmartredis [-lsmartredis-fortran]
Note
Fortran applications need to link in both smartredis-fortran
and
smartredis
libraries whereas C/C++ applications require only
smartredis
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
project(Example)
cmake_minimum_required(VERSION 3.13)
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}
)