diff --git a/docs/source/index.rst b/docs/source/index.rst index 88a70f03..09207a61 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -21,24 +21,14 @@ for deep learning assisted reacting flow simulations. It is also has the scope t .. toctree:: :maxdepth: 3 :numbered: - :caption: Installation - :glob: - - installation/index - -.. _quikstart: - -.. toctree:: - :maxdepth: 3 :caption: Quick Start :glob: - quickstart/index + qs/install + qs/examples + qs/input - - - .. _solvers: .. toctree:: diff --git a/docs/source/installation/index.rst b/docs/source/installation/index.rst deleted file mode 100644 index eb139885..00000000 --- a/docs/source/installation/index.rst +++ /dev/null @@ -1,108 +0,0 @@ - -Install OpenFOAM-7 (if not already installed) -==================================================== - -.. Note:: If Ubuntu is used as the subsystem, please use `Ubuntu:20.04 `_ instead of the latest version. OpenFOAM-7 accompanied by ParaView 5.6.0 is not available for `Ubuntu-latest `_. - -.. code-block:: bash - - sudo sh -c "wget -O - https://dl.openfoam.org/gpg.key | apt-key add -" - sudo add-apt-repository http://dl.openfoam.org/ubuntu - sudo apt-get update - sudo apt-get -y install openfoam7 - -OpenFOAM 7 and ParaView 5.6.0 will be installed in the ``/opt`` directory. - -Source your OpenFOAM -====================== - -.. code-block:: bash - - source $HOME/OpenFOAM/OpenFOAM-7/etc/bashrc - -This depends on your own path for OpenFOAM bashrc. - -Clone the DeepFlame repository -=========================================== - -.. code-block:: bash - - git clone https://github.com/deepmodeling/deepflame-dev.git - cd deepflame-dev - - -Install dependencies and DeepFlame based on your need -================================================================= -DeepFlame supports three compilation choices: no torch, LibTorch, and PyTorch. - - .. Note:: You are encouaged to try all three options, but remember to install the next version in a new terminal to clean previous environment variables. - - - -PyTorch version (**RECOMMEND**) -------------------------------- - -PyTorch version aims to support computation on CUDA. If you have compatible platform, run the following command to install DeepFlame. - -.. code-block:: - - conda create -n df-pytorch python=3.8 - conda activate df-pytorch - conda install -c cantera libcantera-devel - conda install pytorch torchvision torchaudio cudatoolkit=11.6 -c pytorch -c conda-forge - conda install pybind11 - . install.sh --use_pytorch - -.. Note:: You may come accross an error regarding shared library ``libmkl_rt.so.2`` when libcantera is installed through cantera channel. If so, go to your conda environment and check the existance of ``libmkl_rt.so.2`` and ``libmkl_rt.so.1``, and then link ``libmkl_rt.so.2`` to ``libmkl_rt.so.1``. - - -.. code-block:: bash - - cd ~/miniconda3/envs/df-pytorch/lib - ln -s libmkl_rt.so.1 libmkl_rt.so.2 - - -LibTorch version -------------------------------- - -If you choose to use LibTorch (C++ API for Torch), first create the conda env and install `LibCantera `_: - -.. code-block:: bash - - conda create -n df-libtorch - conda activate df-libtorch - conda install -c cantera libcantera-devel - -Then you can pass your own libtorch path to DeepFlame. -.. code-block:: bash - - . install.sh --libtorch_dir /path/to/libtorch/ - - -.. Note:: Some compiling issues may happen due to system compatability. Instead of using conda installed Cantera C++ lib and the downloaded Torch C++ lib, try to compile your own Cantera and Torch C++ libraries. - -No Torch version -------------------------- - -If your are using DeepFlame's CVODE solver without DNN model, just install LibCantera via `conda `_. - -.. code-block:: bash - - conda create -n df-notorch - conda activate df-notorch - conda install -c cantera libcantera-devel - -.. Note:: Check your ``Miniconda3/envs/libcantera`` directory and make sure the install was successful (lib/ include/ etc. exist). - - -If the conda env ``df-notorch`` is activated, install DeepFlame by running: - -.. code-block:: bash - - . install.sh - -If ``df-notorch`` not activated (or you have a self-complied libcantera), specify the path to your libcantera: - -.. code-block:: bash - - . install.sh --libcantera_dir /your/path/to/libcantera/ \ No newline at end of file diff --git a/docs/source/quickstart/0Dcvode.jpg b/docs/source/qs/0Dcvode.jpg similarity index 100% rename from docs/source/quickstart/0Dcvode.jpg rename to docs/source/qs/0Dcvode.jpg diff --git a/docs/source/qs/compile_success.png b/docs/source/qs/compile_success.png new file mode 100644 index 00000000..0967e2ae Binary files /dev/null and b/docs/source/qs/compile_success.png differ diff --git a/docs/source/qs/examples.rst b/docs/source/qs/examples.rst new file mode 100644 index 00000000..b6856563 --- /dev/null +++ b/docs/source/qs/examples.rst @@ -0,0 +1,88 @@ +Two Examples +=================== + +DeepFlame with DNN +-------------------------- + +If you choose to use PyTorch as the integratgor and use the compilation flag `--use_pytorch`, you can run examples stored in `$HOME/deepflame-dev/examples/.../pytorchIntegratgor`. To run an example, you first need to source your OpenFOAM: + +.. code-block:: bash + + source $HOME/OpenFOAM/OpenFOAM-7/etc/bashrc + +Then, source your DeepFlame: + +.. code-block:: bash + + source $HOME/deepflame-dev/bashrc + +Next, you can go to the directory of any example case that you want to run. For example: + +.. code-block:: bash + + cd $HOME/deepflame-dev/examples/zeroD_cubicReactor/H2/pytorchIntegratgor + +This is an example for the zero-dimensional hydrogen combustion with PyTorch as the integrator. All files needed by DNN are stored in `pytorchDNN` folder, and the inference file is `inference.py`. Configurations regarding DNN are included in `constant/CanteraTorchProperties`. + +The case is run by simply typing: + +.. code-block:: bash + + ./Allrun + +.. Note:: Users can go to `constant/CanteraTorchProperties` and check if `torch` is switched on. Switch it `on` to run DNN cases, and switch `off` to run CVODE cases. + +If you plot PyTorch's result together with CVODE's result, the graph is expected to look like: + +.. figure:: pytorch.png + + Visualisation of 0D results from PyTorch and CVODE integrators + + + +DeepFlame without DNN +------------------------------ +CVODE Integrator is the one without the application of Deep Neural Network (DNN). Follow the steps below to run an example of CVODE. Examples are stored in the directory: +.. code-block:: bash + + $HOME/deepflame-dev/examples + +To run these examples, first source your OpenFOAM, depending on your OpenFOAM path: + +.. code-block:: bash + + source $HOME/OpenFOAM/OpenFOAM-7/etc/bashrc + +Then, source your DeepFlame: + +.. code-block:: bash + + source $HOME/deepflame-dev/bashrc + +Next, you can go to the directory of any example case that you want to run. For example: + +.. code-block:: bash + + cd $HOME/deepflame-dev/examples/zeroD_cubicReactor/H2/cvodeIntegrator + +This is an example for the zero-dimensional hydrogen combustion with CVODE integrator. + +The case is run by simply typing: + +.. code-block:: bash + + ./Allrun + +The probe used for post processing is defined in ``/system/probes``. In this case, the probe is located at the coordinates (0.0025 0.0025 0.0025) to measure temperature variation with time. +If the case is successfully run, the result can be found in ``/postProcessing/probes/0/T``, and it can be visualized by running: + +.. code-block:: bash + + gunplot + plot "/your/path/to/postProcessing/probes/0/T" + +You will get a graph: + +.. figure:: 0Dcvode.jpg + + Visualisation of the zero-dimensional hydrogen combustion result with CVODE integrator \ No newline at end of file diff --git a/docs/source/qs/input.rst b/docs/source/qs/input.rst new file mode 100644 index 00000000..afcc24a9 --- /dev/null +++ b/docs/source/qs/input.rst @@ -0,0 +1,59 @@ +Brief Introduction to Inputs +====================================== +The dictionary ``CanteraTorchProperties`` is the original dictionay of DeepFlame. It read in netowrk realted parameters and configurations. It typically looks like: + +.. code-block:: + + chemistry on; + CanteraMechanismFile "ES80_H2-7-16.yaml"; + transportModel "Mix";//"UnityLewis"; + odeCoeffs + { + //"relTol" 1e-15; + //"absTol" 1e-24; + } + inertSpecie "N2"; + + zeroDReactor + { + constantProperty "pressure"; + } + + torch on; + GPU on; + torchModel1 "ESH2-sub1.pt"; + torchModel2 "ESH2-sub2.pt"; + torchModel3 "ESH2-sub3.pt"; + + torchParameters1 + { + Tact 700 ; + Qdotact 3e7; + coresPerGPU 4; + } + torchParameters2 + { + Tact 2000; + Qdotact 3e7; + } + torchParameters3 + { + Tact 2000; + Qdotact 7e8; + } + loadbalancing + { + active false; + //log true; + } + + +In the above example, the meanings of the parameters are: + +* ``CanteraMechanismFile``: the name of the reaction mechanism file +* ``odeCoeffs``: the ode torlerance. 1e-15 and 1e-24 are used for network training, so it should keep the same when comparing results with nd without DNN. +* ``torch``: the switch used to control the on and off of DNN. If users are running CVODE, this needs to be switched off. +* ``GPU``: the switch used to control whether GPU or CPU is used to carry out inference. +* ``torchModel``: name of network. +* ``torchParameters``: thresholds used to decide when to use network. +* ``coresPerGPU``: number of CPU cores on one node. diff --git a/docs/source/qs/install.rst b/docs/source/qs/install.rst new file mode 100644 index 00000000..b3e88358 --- /dev/null +++ b/docs/source/qs/install.rst @@ -0,0 +1,141 @@ +Installation +====================== + +Prerequisites +------------------------ +The installation of DeepFlame is simple and requires **OpenFOAM-7**, **LibCantera**, and **PyTorch**. + +.. Note:: If Ubuntu is used as the subsystem, please use `Ubuntu:20.04 `_ instead of the latest version. OpenFOAM-7 accompanied by ParaView 5.6.0 is not available for `Ubuntu-latest `_. + +First install OpenFOAM-7 if it is not already installed. + +.. code-block:: bash + + sudo sh -c "wget -O - https://dl.openfoam.org/gpg.key | apt-key add -" + sudo add-apt-repository http://dl.openfoam.org/ubuntu + sudo apt-get update + sudo apt-get -y install openfoam7 + +OpenFOAM-7 and ParaView-5.6.0 will be installed in the ``/opt`` directory. + +.. Note:: There is a commonly seen issue when installing OpenFOAM via ``apt-get install`` with an error message: ``could not find a distribution template for Ubuntu/focal``. To resolve this issue, you can refer to `issue#54 `_. + +**LibCantera** and **PyTorch** can be easily installed via `conda `_. If you have compatible platform, run the following command to install DeepFlame. + +.. code-block:: bash + + conda create -n deepflame python=3.8 + conda activate deepflame + conda install -c cantera libcantera-devel + conda install pytorch torchvision torchaudio pytorch-cuda=11.6 -c pytorch -c nvidia + conda install pybind11 easydict + + +.. Note:: Please go to PyTorch's official website to check your system compatability and choose the installation command line that is suitable for your platform. + +.. Note:: Check your ``Miniconda3/envs/deepflame`` directory and make sure the install was successful (lib/ include/ etc. exist). + + +Configure +------------------------- +**1. Source your OpenFOAM-7 bashrc to configure the $FOAM environment.** + +.. Note:: This depends on your own path for OpenFOAM-7 bashrc. + +If you have installed using ``apt-get install``, use: + +.. code-block:: bash + + source /opt/openfoam7/etc/bashrc + +If you compiled from source following the `official guild `_, use: + +.. code-block:: bash + + source $HOME/OpenFOAM/OpenFOAM-7/etc/bashrc + +.. Note:: Check your environment using ``echo $FOAM_ETC`` and you should get the directory path for your OpenFOAM-7 bashrc you just used in the above step. + +**2. Clone the DeepFlame repository:** + +.. code-block:: bash + + git clone https://github.com/deepmodeling/deepflame-dev.git + +**3. Configure the DeepFlame environment:** + +.. code-block:: bash + + cd deepflame-dev + . configure.sh --use_pytorch + source ./bashrc + +.. Note:: Check your environment using ``echo $DF_ROOT`` and you should get the path for the deepflame-dev directory. + +Build and Install +------------------------------- +Finally you can build and install DeepFlame: + +.. code-block:: bash + + . install.sh + +.. Note:: You may come accross an error regarding shared library ``libmkl_rt.so.2`` when libcantera is installed through cantera channel. If so, go to your conda environment and check the existance of ``libmkl_rt.so.2`` and ``libmkl_rt.so.1``, and then link ``libmkl_rt.so.2`` to ``libmkl_rt.so.1``. + +.. code-block:: bash + + cd ~/miniconda3/envs/df-pytorch/lib + ln -s libmkl_rt.so.1 libmkl_rt.so.2 + +**If you have compiled DeepFlame successfully, you should see the print message in your terminal:** + +.. figure:: compile_success.png + +Other Options +------------------------------- +DeepFlame also provides users with LibTorch and CVODE (no DNN version) options. + +**1. If you choose to use LibTorch (C++ API for Torch), first create the conda env and install** `LibCantera `_: + +.. code-block:: bash + + conda create -n df-libtorch + conda activate df-libtorch + conda install -c cantera libcantera-devel + +Then you can pass your own libtorch path to DeepFlame. + +.. code-block:: bash + + cd deepflame-dev + . configure.sh --libtorch_dir /path/to/libtorch/ + source ./bashrc + . install.sh + +.. Note:: Some compiling issues may happen due to system compatability. Instead of using conda installed Cantera C++ lib and the downloaded Torch C++ lib, try to compile your own Cantera and Torch C++ libraries. + + +**2. If you just need DeepFlame's CVODE solver without DNN model, just install LibCantera via** `conda `_. + +.. code-block:: bash + + conda create -n df-notorch + conda activate df-notorch + conda install -c cantera libcantera-devel + +If the conda env ``df-notorch`` is activated, install DeepFlame by running: + +.. code-block:: bash + + cd deepflame-dev + . configure.sh + source ./bashrc + . install.sh + +If ``df-notorch`` not activated (or you have a self-complied libcantera), specify the path to your libcantera: + +.. code-block:: bash + + . configure.sh --libcantera_dir /your/path/to/libcantera/ + source ./bashrc + . install.sh diff --git a/docs/source/quickstart/pytorch.png b/docs/source/qs/pytorch.png similarity index 100% rename from docs/source/quickstart/pytorch.png rename to docs/source/qs/pytorch.png diff --git a/docs/source/quickstart/cvode.rst b/docs/source/quickstart/cvode.rst deleted file mode 100644 index 9a75c85f..00000000 --- a/docs/source/quickstart/cvode.rst +++ /dev/null @@ -1,47 +0,0 @@ -CVODE Intergrator -=================== -CVODE Integrator is the one without the application of Deep Neural Network (DNN), and it can be used to validate PyTorch and LibTorch integrators. -Follow the steps below to run an example of CVODE. Examples are stored in the directory: -.. code-block:: bash - - $HOME/deepflame-dev/examples - -To run these examples, first source your OpenFOAM, depending on your OpenFOAM path: - -.. code-block:: bash - - source $HOME/OpenFOAM/OpenFOAM-7/etc/bashrc - -Then, source your DeepFlame: - -.. code-block:: bash - - source $HOME/deepflame-dev/bashrc - -Next, you can go to the directory of any example case that you want to run. For example: - -.. code-block:: bash - - cd $HOME/deepflame-dev/examples/zeroD_cubicReactor/H2/cvodeIntegrator - -This is an example for the zero-dimensional hydrogen combustion with CVODE integrator. - -The case is run by simply typing: - -.. code-block:: bash - - ./Allrun - -The probe used for post processing is defined in ``/system/probes``. In this case, the probe is located at the coordinates (0.0025 0.0025 0.0025) to measure temperature variation with time. -If the case is successfully run, the result can be found in ``/postProcessing/probes/0/T``, and it can be visualized by running: - -.. code-block:: bash - - gunplot - plot "/your/path/to/postProcessing/probes/0/T" - -You will get a graph: - -.. figure:: 0Dcvode.jpg - - Visualisation of the zero-dimensional hydrogen combustion result with CVODE integrator \ No newline at end of file diff --git a/docs/source/quickstart/index.rst b/docs/source/quickstart/index.rst deleted file mode 100644 index 0e941bc8..00000000 --- a/docs/source/quickstart/index.rst +++ /dev/null @@ -1,18 +0,0 @@ -Examples for Each Chemistry Integrator -========================================= - -DeepFlame provides users with three avaiblable integrators: CVODE, LibTorch, and PyTorch. CVODE integraotr does not include any machine learning capability, while the other two use different APIs to make computation with neural neworks on different platforms possible. -To get a quick start with all three integrators, there are several examples stored in ``/deepflame-dev/examples/`` that can be run. More details regarding each integrator can be found in the following sections. - - -.. _quickstart: - -.. toctree:: - :numbered: - :glob: - - pytorch - libtorch - cvode - - \ No newline at end of file diff --git a/docs/source/quickstart/libtorch.png b/docs/source/quickstart/libtorch.png deleted file mode 100644 index 5a07c1f1..00000000 Binary files a/docs/source/quickstart/libtorch.png and /dev/null differ diff --git a/docs/source/quickstart/libtorch.rst b/docs/source/quickstart/libtorch.rst deleted file mode 100644 index f0e9146f..00000000 --- a/docs/source/quickstart/libtorch.rst +++ /dev/null @@ -1,35 +0,0 @@ -Libtorch Integrator -=================== -If you choose to use LibTorch as the integratgor and use the compilation flag `--libtorch_dir`, you can run examples stored in `$HOME/deepflame-dev/examples/.../libtorchIntegratgor`. To run an example, you first need to source your OpenFOAM: - -.. code-block:: bash - - source $HOME/OpenFOAM/OpenFOAM-7/etc/bashrc - -Then, source your DeepFlame: - -.. code-block:: bash - - source $HOME/deepflame-dev/bashrc - -Next, you can go to the directory of any example case that you want to run. For example: - -.. code-block:: bash - - cd $HOME/deepflame-dev/examples/zeroD_cubicReactor/H2/libtorchIntegratgor - -This is an example for the zero-dimensional hydrogen combustion with LibTorch as the integrator. All files needed by DNN are listed under the case folder. Configurations regarding DNN are included in `constant/CanteraTorchProperties`. - -The case is run by simply typing: - -.. code-block:: bash - - ./Allrun - -.. Note:: Users can go to `constant/CanteraTorchProperties` and check if `torch` is switched on. Switch it `on` to run DNN cases, and switch `off` to run CVODE cases. - -If you plot LibTorch's result together with CVODE's result, the graph is expected to look like: - -.. figure:: libtorch.png - - Visualisation of 0D results from LibTorch and CVODE integrators diff --git a/docs/source/quickstart/pytorch.rst b/docs/source/quickstart/pytorch.rst deleted file mode 100644 index b6b8749f..00000000 --- a/docs/source/quickstart/pytorch.rst +++ /dev/null @@ -1,36 +0,0 @@ -PyTorch Integrator -=================== - -If you choose to use PyTorch as the integratgor and use the compilation flag `--use_pytorch`, you can run examples stored in `$HOME/deepflame-dev/examples/.../pytorchIntegratgor`. To run an example, you first need to source your OpenFOAM: - -.. code-block:: bash - - source $HOME/OpenFOAM/OpenFOAM-7/etc/bashrc - -Then, source your DeepFlame: - -.. code-block:: bash - - source $HOME/deepflame-dev/bashrc - -Next, you can go to the directory of any example case that you want to run. For example: - -.. code-block:: bash - - cd $HOME/deepflame-dev/examples/zeroD_cubicReactor/H2/pytorchIntegratgor - -This is an example for the zero-dimensional hydrogen combustion with PyTorch as the integrator. All files needed by DNN are stored in `pytorchDNN` folder, and the inference file is `inference.py`. Configurations regarding DNN are included in `constant/CanteraTorchProperties`. - -The case is run by simply typing: - -.. code-block:: bash - - ./Allrun - -.. Note:: Users can go to `constant/CanteraTorchProperties` and check if `torch` is switched on. Switch it `on` to run DNN cases, and switch `off` to run CVODE cases. - -If you plot PyTorch's result together with CVODE's result, the graph is expected to look like: - -.. figure:: pytorch.png - - Visualisation of 0D results from PyTorch and CVODE integrators \ No newline at end of file