diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..0631375c --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,19 @@ +version: 2 + +build: + os: "ubuntu-20.04" + tools: + python: "3.8" + +python: + install: + - requirements: docs/requirements.txt + # Install our python package before building the docs + - method: pip + path: . + +sphinx: + fail_on_warning: true +formats: + - pdf + diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..26b94228 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..747ffb7b --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..22749293 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,8 @@ +sphinx>=4.0.2 +recommonmark +sphinx_rtd_theme +sphinx_markdown_tables +sphinx-argparse +myst-parser +deepmodeling_sphinx +. \ No newline at end of file diff --git a/docs/source/communication.rst b/docs/source/communication.rst new file mode 100644 index 00000000..6ee8712e --- /dev/null +++ b/docs/source/communication.rst @@ -0,0 +1,3 @@ +Communication +================ + diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..fd75d26c --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,41 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information +from datetime import date +project = 'DeepFlame' +copyright = '2021-%d, DeepModeling' % date.today().year +author = 'DeepModeling' +release = '0.1' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +import sphinx_rtd_theme +extensions = ["deepmodeling_sphinx", + 'sphinx_rtd_theme', + 'sphinx.ext.duration', + 'sphinx.ext.doctest', + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.intersphinx', +] +source_suffix = ['.rst', '.md'] + +templates_path = ['_templates'] +exclude_patterns = [] + +intersphinx_disabled_domains = ['std'] + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'sphinx_rtd_theme' + + +# -- Options for EPUB output +#epub_show_urls = 'footnote' diff --git a/docs/source/contributors.rst b/docs/source/contributors.rst new file mode 100644 index 00000000..f0f63e2c --- /dev/null +++ b/docs/source/contributors.rst @@ -0,0 +1,4 @@ +Contributors +============ + +.. git-shortlog-authors:: \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..294ab050 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,62 @@ +.. Testing documentation master file, created by + sphinx-quickstart on Thu Aug 25 16:15:41 2022. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +======================================= +Welcome to DeepFlame's Documentation +======================================= + +.. _Overview: + +DeepFlame is a computational fluid dynamics suite for single or multiphase, laminar or turbulent reacting flows at all speeds with machine learning capabilities. It aims to provide an open-source +platform bringing together the individual strengths of `OpenFOAM `_, `Cantera `_ and `pyTorch `_ +for machine learning assisted reacting flow simulations. It is also has the scope to incorporate next-generation heterogenous supercomputing and AI acceleration infrustructures such as GPU and FPGAs. + +.. Note:: This project is under active development + + +.. _User_Guide: + +.. toctree:: + :maxdepth: 3 + :numbered: + :caption: User Guide + :glob: + + installation/index + quickstart/index + solvers/index + + +.. _reference: +.. toctree:: + :maxdepth: 5 + :caption: Reference + :glob: + + + + + +.. _project-details: + +.. toctree:: + :maxdepth: 3 + :numbered: + :caption: Project Details + + + contributors + communication + + +.. _Miscellaneous: + +.. toctree:: + :maxdepth: 3 + :numbered: + :caption: Miscellaneous + + + diff --git a/docs/source/installation/index.rst b/docs/source/installation/index.rst new file mode 100644 index 00000000..ca1dd6be --- /dev/null +++ b/docs/source/installation/index.rst @@ -0,0 +1,65 @@ +Installation +================= + +.. 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 `_. + +The installation of DeepFlame is simple and requires `OpenFOAM-7 `_, `LibCantera `_, and `Libtorch `_. + +Install Dependencies +-------------------------- + +**Install OpenFOAM-7** + +If `OpenFOAM-7 `_ is not installed yet, please follow the instruction given on the official website. After installation, source your OpenFOAM via the default path below (or your own path for OpenFOAM bashrc). + + +.. code-block:: bash + + source $HOME/OpenFOAM/OpenFOAM-7/etc/bashrc + +**Install LibCantera via conda** + +First install Miniconda or Anaconda through commands: + +.. code-block:: bash + + wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh + sh Miniconda3-latest-Linux-x86_64.sh -b + source ~/miniconda3/etc/profile.d/conda.sh + + +Use the commands below to install and activate LibCantera. + +.. code-block:: bash + + conda create -n libcantera + conda activate libcantera + conda install -c cantera libcantera-devel + +.. Note:: Check your Miniconda3/envs/libcantera directory and make sure the install was successful (lib/ include/ etc. exist). + + +**Install Precompiled `Libtorch `_** + +.. code-block:: bash + + wget https://download.pytorch.org/libtorch/cpu/libtorch-cxx11-abi-shared-with-deps-1.11.0%2Bcpu.zip + unzip libtorch-cxx11-abi-shared-with-deps-1.11.0+cpu.zip -d thirdParty + + +Install DeepFlame +----------------------- +**Clone the DeepFlame Repository** + +.. code-block:: bash + + git clone https://github.com/deepmodeling/deepflame-dev.git + cd deepflame-dev + +**Install DeepFlame** + +.. code-block:: bash + + . 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. diff --git a/docs/source/quickstart/index.rst b/docs/source/quickstart/index.rst new file mode 100644 index 00000000..38fc6230 --- /dev/null +++ b/docs/source/quickstart/index.rst @@ -0,0 +1,38 @@ +Quick Start +============== +To get a quick start with DeepFlame, there are several examples for each solver stored in the following directory that can be run. + +.. 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/cvodeSolver + +This is an example for the zero-dimensional hydrogen combustion with CVODE Solver. + +The case is run by simply typing: + +.. code-block:: bash + + ./Allrun + +.. Note:: For the example cases with torchSolver, an additional DNN model file in the `.pt` format is required. Please contact the developers if you would like a test run. + + + diff --git a/docs/source/solvers/1D_air_detonation.png b/docs/source/solvers/1D_air_detonation.png new file mode 100644 index 00000000..0183ee7b Binary files /dev/null and b/docs/source/solvers/1D_air_detonation.png differ diff --git a/docs/source/solvers/1D_reactive_shock_tube.png b/docs/source/solvers/1D_reactive_shock_tube.png new file mode 100644 index 00000000..7584e25f Binary files /dev/null and b/docs/source/solvers/1D_reactive_shock_tube.png differ diff --git a/docs/source/solvers/df0DFoam.md b/docs/source/solvers/df0DFoam.md new file mode 100644 index 00000000..b72f0144 --- /dev/null +++ b/docs/source/solvers/df0DFoam.md @@ -0,0 +1,2 @@ +df0DFoam +============== diff --git a/docs/source/solvers/dfHighSpeedFoam.rst b/docs/source/solvers/dfHighSpeedFoam.rst new file mode 100644 index 00000000..9750c660 --- /dev/null +++ b/docs/source/solvers/dfHighSpeedFoam.rst @@ -0,0 +1,78 @@ +dfHighSpeedFoam +================== + +One-Dimensional Reactive Shock Tube +---------------------------------------- + + +**Problem Description** + + +The case simulates supersonic inlet flow hitting the wall and then reflected to ignite the premixed gas. The reactive wave will catch the reflected shock wave. This case can also verify the accuracy of our solver in capturing the interaction of convection and reaction. + + +.. list-table:: Operating Conditions in Brief + :widths: 40 40 + :header-rows: 0 + + * - Chamber size (x) + - 0.12m + * - Initial Gas Density + - 0.072 kg/m^3 (x<=0.06 m), 0.18075 kg/m^3 (x>0.06 m) + * - Initial Gas Pressure + - 7173 Pa (x<=0.06 m), 35594 Pa (x>0.06 m) + * - Initial Gas Velocity + - 0 m/s (x<=0.06 m), -487.34 m/s (x>0.06 m) + * - Ideal Gas Composition (mole fraction) + - H2/O2/Ar = 2/1/7 + + +**Output** + + +.. figure:: 1D_reactive_shock_tube.png + + + Result of one-dimensional reactive shock tube + + + +One-Dimensional H2/Air Detonation +-------------------------------------------- + +**Problem Description** + + +Detonation propagation contains a complex interaction of the leading shock wave and auto-igniting reaction, showing the coupling of shock wave and chemical reaction. This case aims to validate the accuracy of this solver in capturing this process and the propagation speed. + + +.. list-table:: Operating Conditions in Brief + :widths: 40 40 + :header-rows: 0 + + * - Chamber size (x) + - 0.5m + * - Initial Gas Pressure + - 90 atm (hot spot), 1 atm (other area) + * - Initial Gas Temperature + - 2000 K (hot spot), 300 K (other area) + * - Ideal Gas Composition (mole fraction) + - H2/O2/N2 = 2/1/3.76 + (homogeneous stoichiometric mixture) + + + + + +**Output** + + +.. figure:: 1D_air_detonation.png + + Result of one-dimensional H2/air detonation + + + +Reference +--------------- +E S Oran, T. R. Young, J. P. Boris, A. Cohen, Weak and strong ignition. i. Numerical simulations of shock tube experiments, Combustion and Flame 48 (1982) 135-148. \ No newline at end of file diff --git a/docs/source/solvers/dfLowMachFoam.md b/docs/source/solvers/dfLowMachFoam.md new file mode 100644 index 00000000..2ec62a40 --- /dev/null +++ b/docs/source/solvers/dfLowMachFoam.md @@ -0,0 +1,2 @@ +dfLowMachFoam +==================== \ No newline at end of file diff --git a/docs/source/solvers/dfSprayFoam.rst b/docs/source/solvers/dfSprayFoam.rst new file mode 100644 index 00000000..460f9cad --- /dev/null +++ b/docs/source/solvers/dfSprayFoam.rst @@ -0,0 +1,40 @@ +dfSprayFoam +================= + +aachenBomb +------------------ + +**Problem Description** + + +This case simulates combustion inside a constant volume chamber based on an experimental setup at RWTH Aachen University. It can mimic, for example, the beginning of power stroke in a four-stroke diesel engine. + + + +.. list-table:: Operating Conditions in Brief + :widths: 40 40 + :header-rows: 0 + + * - Chamber size (xyz) + - 0.02×0.1×0.02m^3 + * - Initial Gas Temperature + - 800K + * - Initial Gas Pressure + - 5MPa + * - Initial Gas Composition (mass fraction) + - 23.4% O2, 76.6% N2 + * - Fuel + - n-heptane + * - Fuel Temperature at the Nozzle + - 320K + * - Fuel Injection Duration + - 1.25ms + * - Total Injection Mass + - 6mg + + + +**Configurations Different from OpenFOAM Case** + + +Cantera is used instead of the built-in modules of OpenFOAM to solve the chemical reactions. Therefore, a chemical mechanism file in YAML format is required in the case directory, and the full name of the mechanism file ("xxx. YAML") should be the entry after the keyword **CanteraMechanismFile** in *constant/CanteraTorchProperties*. Non-reacting simulation can be conducted by switching the entry after the keyword **chemistry** from **on** to **off** in *constant/CanteraTorchProperties*. \ No newline at end of file diff --git a/docs/source/solvers/index.rst b/docs/source/solvers/index.rst new file mode 100644 index 00000000..5ad283f2 --- /dev/null +++ b/docs/source/solvers/index.rst @@ -0,0 +1,10 @@ +Solvers +============ + +.. toctree:: + :maxdepth: 1 + + df0DFoam + dfLowMachFoam + dfHighSpeedFoam + dfSprayFoam diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 00000000..ad1b7501 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,10 @@ +[build-system] +requires = [ + "setuptools", + "setuptools_scm", + "wheel", + "scikit-build", + "cmake", + # see https://github.com/scikit-build/scikit-build/releases/tag/0.13.1 + "ninja; platform_system!='Windows'", +]