Installation
The following components are required to use the SmartFlow framework:
For comprehensive installation instructions, please refer to the official documentation for each component:
If you plan to contribute advanced features to the framework, we recommend thoroughly reviewing both the SmartSim Documentation and Stable-Baselines3 Documentation documentation.
Below is a quick installation guide for all components. Note that Python 3.9–3.11 is required for compatibility. We recommend starting with a fresh virtual environment if your system has already installed Python packages. For local computer users (apart from HPC using), we recommend using
python -m venv /path/to/smartflow/environment
source /path/to/smartflow/environment/bin/activate
Also you can use anaconda to create and manage your virtual environment:
# Create a new conda environment named "smartflow" with Python 3.10
conda create -n smartflow python=3.10
conda activate smartflow
If you are using a High Performance Computing (HPC) system, please ensure that the Python version is compatible with the system’s modules. You can check the available Python versions by running:
module avail python
You should load the following modules before installing the packages:
module load OpenMPI/4.1.5-GCC-12.3.0
module load Python/3.11.3-GCCcore-12.3.0
module load GCCcore/12.3.0
module load virtualenv/20.23.1-GCCcore-12.3.0
module load CMake/3.26.3-GCCcore-12.3.0
module load GCC/12.3.0
module load FFTW/3.3.10-GCC-12.3.0
After loading the modules, you can create a virtual environment using the following command:
virtualenv /path/to/smartflow/environment
# Activate the virtual environment
source /path/to/smartflow/environment/bin/activate
# load the modules again in your current working environment
module load OpenMPI/4.1.5-GCC-12.3.0
module load Python/3.11.3-GCCcore-12.3.0
module load GCCcore/12.3.0
module load virtualenv/20.23.1-GCCcore-12.3.0
module load CMake/3.26.3-GCCcore-12.3.0
module load GCC/12.3.0
module load FFTW/3.3.10-GCC-12.3.0
Note
If there are no extra notes for installing the smartflow packages in HPC, you can follow the same steps as in local computer installation.
Note
SmartFlow fully supports OpenMPI by default. Using other MPI implementations may require extra setup or tuning.
1. SmartSim and SmartRedis
SmartSim provides the infrastructure for launching and managing simulations, while SmartRedis provides client interfaces for interacting with the in-memory Redis database.
Python Installation
# Install SmartSim
pip install smartsim
# Build SmartSim with CPU support and Dragon
smart build --device cpu --dragon
# If you are using HPC, you shall load cmake and pay attention to cmake version.
# Install SmartRedis Python client
pip install smartredis
Note
The --dragon option is not required essentially. The following command also works:
smart build --device cpu
C, C++, and Fortran Client Libraries
For compiled language applications, the SmartRedis client libraries need to be built from source. We currently use version 0.5.3 for compatibility.
Using GCC Compilers
git clone https://github.com/CrayLabs/SmartRedis --depth=1 --branch=v0.5.3 smartredis
cd smartredis
make lib-with-fortran CC=gcc CXX=g++ FC=gfortran
After compilation, add the library path to your environment:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/smartredis/lib
# Add this to your .bashrc or .bash_profile for persistence
Using NVIDIA Compilers (for GPU-enabled applications)
cd smartredis
make lib-with-fortran CC=nvc CXX=nvc++ FC=nvfortran
Installation Notes and Verification
The CFD solver, SmartRedis, and SmartRedis-MPI must be compiled with the same compiler to ensure proper linking.
The command smart build --device cpu --dragon not only builds SmartSim with CPU and Dragon support,
but also installs and configures RedisAI, enabling machine learning model execution within Redis.
After the installation, you can verify the setup using the following command:
smart info
If the installation is successful, you should see output similar to the following:
Smart Python Packages:
╒════════════╤═══════════╕
│ Name │ Version │
╞════════════╪═══════════╡
│ SmartSim │ 0.7.0 │
│ SmartRedis │ 0.5.3 │
╘════════════╧═══════════╛
Orchestrator Configuration:
╒═══════════╤═════════════════════════════════════════════════════════════════════════════════════╕
│ Installed │ REDIS │
│ Location │ /smartsod2d/lib/python3.10/site-packages/smartsim/_core/bin/redis-cli │
╘═══════════╧═════════════════════════════════════════════════════════════════════════════════════╛
Redis AI Configuration:
╒══════════╤══════════════════════════════════════════════════════════════════════════════════════╕
│ Status │ Installed │
│ Location │ /smartsod2d/lib/python3.10/site-packages/smartsim/_core/lib/redisai.so │
╘══════════╧══════════════════════════════════════════════════════════════════════════════════════╛
Machine Learning Backends:
╒════════════╤═════════════════════╤══════════════════╕
│ Name │ Backend Available │ Python Package │
╞════════════╪═════════════════════╪══════════════════╡
│ Tensorflow │ True │ 2.15.0 │
│ Torch │ True │ 2.6.0 │
│ ONNX │ False │ Not Installed │
╘════════════╧═════════════════════╧══════════════════╛
2. Stable-Baselines3
Stable-Baselines3 is a Python library that provides implementations of reinforcement learning algorithms. It can be installed with the following command:
pip install stable-baselines3[extra]
3. SmartFlow
We recommand to use SmartFlow-v1.0.1 as a stable version.
To install SmartFlow, clone the repository and install the required packages:
# Directory where you want to clone the repository
cd /your/local/dir/code
# Clone the SmartFlow repository
git clone https://github.com/soaringxmc/SmartFlow.git --branch=v1.0.1
SmartFlow is installed with the following commands:
cd SmartFlow
pip install -e .
This will mark the current package as editable, so it can be modified and the changes will be automatically available to the Python environment.
Scripts Installation
The scripts in SmartFlow rely on additional Python packages that may not be listed in the default installation. In particular, make sure the following libraries are installed:
omegaconfwandb
You can install them with:
pip install omegaconf wandb
4. SmartRedis-MPI
Before installing the CFD solver, build the SmartRedis-MPI library that will be linked by the MPI-based parallel CFD solver:
git clone https://github.com/soaringxmc/smartredis-mpi.git
cd smartredis-mpi
Edit the Makefile to set the correct settings and paths to your SmartRedis installation:
The Makefile is located in the folder of the smartredis-mpi repository
vim Makefile
# Adjust the paths in the Makefile
# in line 2 set the compiler
COMPILER =GNU
# In line 4 set set the precision
SINGLE_PRECISION = 0
# In line 6 set the smartredis installation path, it should be the same as the one you set in the SmartRedis installation (step 1) or the one you set in the SmartRedis-MPI installation (step 4)
SMARTREDIS INSTALL DIR = /your/local/dir/code/smartredis/instal1
# after all your settings are done, run the following command to build the library
make clean
make
Add the library path to your environment:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/your/dir/smartredis-mpi/build/lib
# Add this to your .bashrc or .bash_profile for persistence
5. CFD Solver
The advantage of SmartFlow is that it can be easily integrated with any CFD solver. Only several lines of code need to be added to the CFD solver to enable communication with the SmartFlow framework.
As an example, we only added five lines of code to the CaLES solver to enable its coupling with the SmartFlow framework.
To use SmartFlow v1.0.1 with CaLES, please ensure you are using the compatible version: CaLES-v2.0.0-smartflow
# Clone the CaLES repository smartflow branch
cd /your/local/dir/code
git clone -b smartflow https://github.com/CaNS-World/CaLES.git
If you want to use CaLES as your CFD solver or simply test the workflow of the SmartFlow framework, please refer to the CaLES for installation instructions. After installing the CaLES solver, you shall update the dependencies as follows:
# your CaLES installation directory
cd /your/local/dir/code/CaLES
# update the submodules
git submodule update --init --recursive
After that, you can build the solver with the following command:
# in your current working directory, clean all cache
make allclean
# build the solver
make libs && make -j
If you are installing the CaLES solver on your High Performance Computing (HPC), you should pay extra attention to the libs.mk file, which is located in the CaLES/configs directory. In libs.mk, you should set the proper paths before making it as shown in the last fours lines of the document:
# in your current CaLES working directory
vim configs/libs.mk
# set the paths
override LIBS += -L/path/to/your/smartredis/install/lib -lsmartredis -lsmartredis-fortran
override INCS += -I/path/to/your/smartredis/install/include
override LIBS += -L/path/to/your/smartredis-mpi/build/lib -lsmartredis_mpi
override INCS += -I/path/to/your/smartredis-mpi/build/include
Compilation Options
Branch Selection: Make sure to use the
smartflow branch, not the main branch.Build Configuration: Ensure that the parameter
PENCIL_AXISis set to 3 in thebuild.conffile.
We suggest presenting the CFD solvers coupled to SmartFlow in the following table:
Solver |
Coupling Status |
Device Support |
Numerical Method |
|---|---|---|---|
CaLES |
Coupled |
CPU/GPU |
Finite Difference |
SOD2D |
Coupled |
CPU/GPU |
Spectral Element |
FLEXI |
In progress |
CPU |
Discontinuous Galerkin |
HORSES3D |
In progress |
CPU |
Discontinuous Galerkin |