This library aims at running ML models in C++ and Fortran programs. The library is mainly designed for deploying neural networks in CFD software, the extensions in OpenFOAM and CFL3D might reduce the burden of integrating ML with CFD software.
The following features might be useful to you:
- TensorFlow Backends: Support loading *.pb graph and SavedModel format.
- ONNX Backends: Support loading *.onnx ML models (from PyTorch, Sklearn, etc)
- Support memory layout transpose when set/get data to/from nodes
- Automatic type casting according to the type of your data container and node definition
- Vectorizatized casting and transposing is integrated through Eigen
- Basic APIs in C++ and Fortran
- Extensions in OpenFOAM and CFL3D to assist CFD simulation
#include "predictor.h" //header
// Load the Graph:
Predictor pd("graph.pb");
// Register the nodes in graph that you want to set input data in or get the output data
pd.regist_node("your_input_name", Settings::INPUT_NODE);
pd.regist_node("your_output_name", Settings::OUTPUT_NODE);
// If the tensorshape in your nodes is with unknown dimension, e.g., [-1, 3]
// set the unknown dimension with exact number of examples you want to predict
pd.set_data_count(n_data);
// Create the input data to feed
std::vector<float> data_in({/* some data */});
// Feed data to the inputs
pd.set_node_data("your_input_name", data_in);
// Run the model
pd.run();
// Create a container to hold output data, suppose the shape of "your_output_name" is [-1, 3, 2], then
int n_known_dim = 3 * 2;
std::vector<float> data_out(n_data * n_known_dim);
// Retrieve data from the outputs
pd.get_node_data("your_output_name", data_out)
A library wrapper is also provided for runtime selection specified by $NNPRED_BACKEND. One can simple create a DynPredictor instance by:
#include "dyn_predictor.h" // Header
DynPredictor pd("graph.pb"); // Load the Graph:
// Other lines are the same as the minimal example ...The first step is to activate this folder by executing the script:
source activate.shThis script sets the necessary environmental variables to properly compile the library. The Predictor-Core needs to be compiled firstly, as the OpenFOAM-Extension and CFL3D-Extension all depends on the core predictor.
The Predictor-Core supports two different backends, The TF backends rely on Tensorflow C-API, the dependencies are as follows:
The dependency of ONNX backends is:
By executing the download scripts they will be downloaded into third_party directory:
cd Predictor-Core/third_party
./DownloadThirdParty.shThe backend is specified by an environmental variable in the activate.sh file. One can modify the script or set the environment variable manually in the shell command line.
export NNPRED_BACKEND=ONNX # ONNX Runtime backend
export NNPRED_BACKEND=TF # TensorFlow backend# Go to the source file dir:
cd Predictor-Core
# build the core predictor and test program
make cxxso # the core predictor in C++
make cxxso_dyn # predictor for runtime-switch backend
make cxxtest # C++ test program without running
make run # C++ test program and run
# build fortran extension and test program
make f90so # fortran API
make f90test # fortran test program without running
make runf # fortran test program and runAfter the cxxso compilation target, both backends are compiled by default in Predictor-Core/outputs/lib:
libPredictor_tf.so # Static predictor library for tensorflow backend
libPredictor_onnx.so # Static predictor library for onnx backend A symbolic link pointing to the library is also created, specified by the environmental variable $NNPRED_BACKEND.
libPredictor.so # point to libPredictor_tf.so or libPredictor_onnx.so due to $NNPRED_BACKENDThe cxxso_dyn target will created a dynamic predictor library, which read different backends during runtime:
libDynPredictor.so # Instansiate different backend specified by $NNPRED_BACKEND during runtimeIf the backend needs to be changed, one can modify $NNPRED_BACKEND and execute the make target:
make alias-predictor # Create the symbolic link to the backend librarywhich will link libPredictor.so to libPredictor_tf.so or libPredictor_onnx.so according to $NNPRED_BACKEND
you might need to add the compiled libraries (located in ./Predictor-Core/outputs/lib) in your $LD_LIBRARY_PATH. This operation is done by sourcing the activate.sh at the beginning of the tutorial.
The installation of OpenFOAM-Extension and CFL3D-Extension please refer to the README.md in each separate folder.
For OpenFOAM Users, the Allwmake script could automatically compile all the OpenFOAM related binaries:
./Allwmake # Should build all the OpenFOAM related targets.If you want to use the locally installed libs, please modify the two environment variables set in the activate.sh to point at the locally installed path:
export MY_EIGEN_HOME=your/eigen/dir
export MY_TF_HOME=your/TF/dir/with/libtensorflow.so
export MY_ONNX_HOME=your/ONNX/runtime/library/dirThe API are all demonstrated with a simple A+B=C model, the PDF files can be found as follows:
- C++ example and API document
- Fortran example and API document
- OpenFOAM example and API document
- Explanation on CFL3D ML module
If this software brings convenience to you, please consider citing the following paper, reported in the bibtex entries:
@article{NNPred,
title={NNPred: Deploying neural networks in computational fluid dynamics codes to facilitate data-driven modeling studies},
author={Liu, Weishuo and Song, Ziming and Fang, Jian},
journal={Computer Physics Communications},
pages={108775},
year={2023},
publisher={Elsevier}
}
The source files in the Predictor-Core folder are freely available under the MIT License.
The files in the OpenFOAM-Extension folder are published under GNU Lesser General Public License (LGPL), Version 3. The files in the CFL3D-Extension folder are published under Apache License, Version 2.