Document

.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
+

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)

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

docs/requirements.txt

@@ -0,0 +1,8 @@
+sphinx>=4.0.2
+recommonmark
+sphinx_rtd_theme
+sphinx_markdown_tables
+sphinx-argparse
+myst-parser
+deepmodeling_sphinx
+.

docs/source/communication.rst

@@ -0,0 +1,3 @@
+Communication
+================
+

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'

docs/source/contributors.rst

@@ -0,0 +1,4 @@
+Contributors
+============
+
+.. git-shortlog-authors::

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 <https://openfoam.org/>`_, `Cantera <https://cantera.org/>`_ and `pyTorch <https://pytorch.org/libraries>`_
+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
+
+
+

docs/source/installation/index.rst

@@ -0,0 +1,65 @@
+Installation
+=================
+
+.. Note:: If Ubuntu is used as the subsystem, please use `Ubuntu:20.04 <https://releases.ubuntu.com/focal/>`_ instead of the latest version. OpenFOAM-7 accompanied by ParaView 5.6.0 is not available for `Ubuntu-latest <https://releases.ubuntu.com/jammy/>`_.  
+
+The installation of DeepFlame is simple and requires `OpenFOAM-7 <https://openfoam.org/version/7/>`_, `LibCantera <https://anaconda.org/conda-forge/libcantera-devel>`_, and `Libtorch <https://pytorch.org/>`_.
+
+Install Dependencies
+--------------------------
+
+**Install OpenFOAM-7**
+
+If `OpenFOAM-7 <https://openfoam.org/version/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 <https://pytorch.org/>`_**
+
+.. 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.

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.
+
+
+

docs/source/solvers/df0DFoam.md

@@ -0,0 +1,2 @@
+df0DFoam
+==============

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.

docs/source/solvers/dfLowMachFoam.md

@@ -0,0 +1,2 @@
+dfLowMachFoam
+====================