diff --git a/CMakeLists.txt b/CMakeLists.txt
index a76751f64600ed3d5140ac69c80799745be011d2..0e0bb22ca538e6a1fb1c835403a78d42b78c0e80 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -54,6 +54,7 @@ project(TurTLE
LANGUAGES CXX)
+set(CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/cmake ${CMAKE_MODULE_PATH})
set(CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/cmake/morse ${CMAKE_MODULE_PATH})
set(TURTLE_LIBS "")
@@ -62,6 +63,79 @@ if(NDEBUG)
add_definitions(-DNDEBUG)
endif()
+# taken from https://vicrucann.github.io/tutorials/quick-cmake-doxygen/
+# indicate the documentation build as an option and set it to ON by default
+option(BUILD_DOC "Build documentation" OFF)
+
+# check if Doxygen is installed
+find_package(Doxygen)
+if (DOXYGEN_FOUND)
+ # set input and output files
+ set(DOXYGEN_IN ${CMAKE_CURRENT_SOURCE_DIR}/documentation/cpp/cpp_config)
+ set(DOXYGEN_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+
+ # request to configure the file
+ configure_file(${DOXYGEN_IN} ${DOXYGEN_OUT} @ONLY)
+ message("Doxygen build started")
+
+ # note the option ALL which allows to build the docs together with the application
+ add_custom_target( doc_doxygen
+ COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_OUT}
+ WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+ COMMENT "Generating API documentation with Doxygen"
+ VERBATIM )
+else (DOXYGEN_FOUND)
+ message("Doxygen needs to be installed to generate the doxygen documentation")
+endif (DOXYGEN_FOUND)
+
+# check if sphinx is available
+find_package(Sphinx)
+if (SPHINX_FOUND)
+ if(NOT DEFINED SPHINX_THEME)
+ set(SPHINX_THEME default)
+ endif()
+
+ if(NOT DEFINED SPHINX_THEME_DIR)
+ set(SPHINX_THEME_DIR)
+ endif()
+
+ # configured documentation tools and intermediate build results
+ set(BINARY_BUILD_DIR "${CMAKE_CURRENT_BINARY_DIR}/sphinx_build")
+
+ # Sphinx cache with pickled ReST documents
+ set(SPHINX_CACHE_DIR "${CMAKE_CURRENT_BINARY_DIR}/sphinx_doctrees")
+
+ # HTML output directory
+ set(SPHINX_HTML_DIR "${CMAKE_CURRENT_BINARY_DIR}/sphinx_html")
+ # LaTeX output directory
+ set(SPHINX_LATEX_DIR "${CMAKE_CURRENT_BINARY_DIR}/sphinx_latex")
+
+ configure_file(
+ "${PROJECT_SOURCE_DIR}/documentation/conf.py.in"
+ "${BINARY_BUILD_DIR}/conf.py"
+ @ONLY)
+
+ add_custom_target(doc_html
+ ${SPHINX_EXECUTABLE}
+ -q -b html
+ -c "${BINARY_BUILD_DIR}"
+ -d "${SPHINX_CACHE_DIR}"
+ "${PROJECT_SOURCE_DIR}/documentation"
+ "${SPHINX_HTML_DIR}"
+ COMMENT "Building HTML documentation with Sphinx")
+
+ add_custom_target(doc_latex
+ ${SPHINX_EXECUTABLE}
+ -q -b latex
+ -c "${BINARY_BUILD_DIR}"
+ -d "${SPHINX_CACHE_DIR}"
+ "${PROJECT_SOURCE_DIR}/documentation"
+ "${SPHINX_LATEX_DIR}"
+ COMMENT "Building LaTeX documentation with Sphinx")
+else (SPHINX_FOUND)
+ message("Sphinx needs to be installed to generate the full documentation")
+endif (SPHINX_FOUND)
+
option(TIMING_OUTPUT "Toggle timing output. WARNING: memory usage is proportional to `niter_todo`" OFF)
if(TIMING_OUTPUT)
add_definitions(-DUSE_TIMINGOUTPUT)
diff --git a/README.rst b/README.rst
index 0997e9bc97ff11be477955163c44f5099358c543..0940247b080c8f37832b70ba875d6b9422119a22 100644
--- a/README.rst
+++ b/README.rst
@@ -1,5 +1,7 @@
-.. image:: https://gitlab.mpcdf.mpg.de/mjr/bfps/badges/develop/build.svg
- :target: https://gitlab.mpcdf.mpg.de/mjr/bfps/commits/develop
+.. only:: html
+
+ .. image:: https://gitlab.mpcdf.mpg.de/mjr/bfps/badges/develop/build.svg
+ :target: https://gitlab.mpcdf.mpg.de/mjr/bfps/commits/develop
=========================================
Turbulence Tools: Lagrangian and Eulerian
diff --git a/cmake/FindSphinx.cmake b/cmake/FindSphinx.cmake
new file mode 100644
index 0000000000000000000000000000000000000000..6e9efe350e5860f5fabea2d6695046313c85b593
--- /dev/null
+++ b/cmake/FindSphinx.cmake
@@ -0,0 +1,17 @@
+# taken from https://eb2.co/blog/2012/03/sphinx-and-cmake-beautiful-documentation-for-c---projects/
+
+find_program(SPHINX_EXECUTABLE NAMES sphinx-build
+ HINTS
+ $ENV{SPHINX_DIR}
+ PATH_SUFFIXES bin
+ DOC "Sphinx documentation generator"
+)
+
+include(FindPackageHandleStandardArgs)
+
+find_package_handle_standard_args(Sphinx DEFAULT_MSG
+ SPHINX_EXECUTABLE
+)
+
+mark_as_advanced(SPHINX_EXECUTABLE)
+
diff --git a/cpp/kspace.cpp b/cpp/kspace.cpp
index 86d692a25c099ab5d97dd0fd5b247533815e61b6..06afe4a88fbe6c1b1a05040dfbbae72d73c68d18 100644
--- a/cpp/kspace.cpp
+++ b/cpp/kspace.cpp
@@ -286,8 +286,8 @@ void kspace<be, dt>::ball_filter(
* Filter's Fourier space expression:
* \f[
* \hat{\phi^M_\ell}(k) =
- * \exp(-\frac{(3.54 k \ell)^(122*(\ell)^(0.0836))}{2})
- * \left( 1 + \frac{(k \eta/0.0636)^3.44}{1 + (k \eta/ 0.0621)^3.44} \right)^{1/2}
+ * \exp(-\frac{(3.54 k \ell)^{122 \ell^{0.0836}}}{2})
+ * \left( 1 + \frac{(k \eta/0.0636)^{3.44}}{1 + (k \eta/ 0.0621)^{3.44}} \right)^{1/2}
* \f]
*/
template <field_backend be,
@@ -352,25 +352,33 @@ void kspace<be, dt>::Gauss_filter(
* a Gaussian filter and a sharp real space spherical filter.
*
* Filter expressions in real space are as follows:
- * \f{eqnarray*}{
- * \phi^b_\ell(r) &=&
- * \frac{1}{\ell^3}\frac{6}{\pi} H(\ell/2 - r) \\
- * \phi^g_\ell(r) &=&
+ * \f[
+ * \phi^b_\ell(r) =
+ * \frac{1}{\ell^3}\frac{6}{\pi} H(\ell/2 - r)
+ * \f]
+ * \f[
+ * \phi^g_\ell(r) =
* \frac{1}{\sigma_\ell^3}\frac{1}{(2\pi)^{3/2}}
- * \exp\left(-\frac{1}{2}\left(\frac{r}{\sigma_\ell}\right)^2\right) \\
- * \phi^s_\ell(r) &=&
+ * \exp\left(-\frac{1}{2}\left(\frac{r}{\sigma_\ell}\right)^2\right)
+ * \f]
+ * \f[
+ * \phi^s_\ell(r) =
* \frac{1}{2 \pi^2 r^3}
* \left(\sin k_\ell r - k_\ell r \cos k_\ell r\right)
- * \f}
+ * \f]
* and the corresponding expressions in Fourier space are:
- * \f{eqnarray*}{
- * \hat{\phi^b_\ell}(k) &=&
+ * \f[
+ * \hat{\phi^b_\ell}(k) =
* \frac{3}{2(k\ell/2)^3}
- * \left(2\sin (k \ell/2) - k \ell \cos (k \ell/2)\right) \\
- * \hat{\phi^g_\ell}(k) &=&
- * \exp\left(-\frac{1}{2}k^2 \sigma_\ell^2\right) \\
- * \hat{\phi^s_\ell}(k) &=& H(k_\ell - k)
- * \f}
+ * \left(2\sin (k \ell/2) - k \ell \cos (k \ell/2)\right)
+ * \f]
+ * \f[
+ * \hat{\phi^g_\ell}(k) =
+ * \exp\left(-\frac{1}{2}k^2 \sigma_\ell^2\right)
+ * \f]
+ * \f[
+ * \hat{\phi^s_\ell}(k) = H(k_\ell - k)
+ * \f]
*
* \f$ k_\ell \f$ is given as a parameter, and then we use
* \f[
@@ -425,25 +433,38 @@ int kspace<be, dt>::filter(
* a Gaussian filter and a sharp real space spherical filter.
*
* Filter expressions in real space are as follows:
- * \f{eqnarray*}{
- * \phi^b_\ell(r) &=&
- * \frac{1}{\ell^3}\frac{6}{\pi} H(\ell/2 - r) \\
- * \phi^g_\ell(r) &=&
- * \frac{1}{\sigma_\ell^3}\frac{1}{(2\pi)^{3/2}}
- * \exp\left(-\frac{1}{2}\left(\frac{r}{\sigma_\ell}\right)^2\right) \\
- * \phi^s_\ell(r) &=&
- * \frac{1}{2 \pi^2 r^3}
- * \left(\sin k_\ell r - k_\ell r \cos k_\ell r\right)
- * \f}
+ * \rst
+ * .. math::
+ * :nowrap:
+ *
+ * \begin{eqnarray*}
+ * \phi^b_\ell(r) &=&
+ * \frac{1}{\ell^3}\frac{6}{\pi} H(\ell/2 - r) \\
+ * \phi^g_\ell(r) &=&
+ * \frac{1}{\sigma_\ell^3}\frac{1}{(2\pi)^{3/2}}
+ * \exp\left(-\frac{1}{2}\left(\frac{r}{\sigma_\ell}\right)^2\right) \\
+ * \phi^s_\ell(r) &=&
+ * \frac{1}{2 \pi^2 r^3}
+ * \left(\sin k_\ell r - k_\ell r \cos k_\ell r\right)
+ * \end{eqnarray*}
+ *
+ * \endrst
+ *
* and the corresponding expressions in Fourier space are:
- * \f{eqnarray*}{
- * \hat{\phi^b_\ell}(k) &=&
- * \frac{3}{2(k\ell/2)^3}
- * \left(2\sin (k \ell/2) - k \ell \cos (k \ell/2)\right) \\
- * \hat{\phi^g_\ell}(k) &=&
- * \exp\left(-\frac{1}{2}k^2 \sigma_\ell^2\right) \\
- * \hat{\phi^s_\ell}(k) &=& H(k_\ell - k)
- * \f}
+ * \rst
+ * .. math::
+ * :nowrap:
+ *
+ * \begin{eqnarray*}
+ * \hat{\phi^b_\ell}(k) &=&
+ * \frac{3}{2(k\ell/2)^3}
+ * \left(2\sin (k \ell/2) - k \ell \cos (k \ell/2)\right) \\
+ * \hat{\phi^g_\ell}(k) &=&
+ * \exp\left(-\frac{1}{2}k^2 \sigma_\ell^2\right) \\
+ * \hat{\phi^s_\ell}(k) &=& H(k_\ell - k)
+ * \end{eqnarray*}
+ *
+ * \endrst
*
* \f$\sigma_\ell\f$ and \f$k_\ell\f$ are calibrated such that the energy of
* the large scales is approximately the same (within the inertial range)
diff --git a/cpp/mainpage.dox b/cpp/mainpage.dox
new file mode 100644
index 0000000000000000000000000000000000000000..63151e345be74ea2a1e9acc4b283685b1155057d
--- /dev/null
+++ b/cpp/mainpage.dox
@@ -0,0 +1,32 @@
+/** \mainpage
+ *
+ * Turbulence Tools: Lagrangian and Eulerian
+ * =========================================
+ *
+ * In brief, this code runs pseudospectral direct numerical simulations
+ * (DNS) of the incompressible Navier-Stokes equations, using FFTW 3, and
+ * it can integrate particle trajectories in the resulting fields.
+ *
+ * The Navier-Stokes solver has been extensively tested (tests are included
+ * in the repository), and it is working as expected. Parameters and
+ * statistics are stored in HDF5 format, together with code information, so
+ * simulation data should be "future proof" --- suggestions of possible
+ * improvements to the current approach are always welcome.
+ *
+ * The primary aim of TurTLE is to reduce the time spent on setting up and
+ * baby sitting DNS, as well as simplify the analysis of the generated
+ * data. The wish is that this Python package provides an easy and general
+ * way of constructing efficient specialized DNS C++ codes for different
+ * turbulence problems encountered in research. At the same time, the
+ * package should provide a unified way of postprocessing, and accessing
+ * the postprocessing results. The code therefore consists of two main
+ * parts: the pure C++ code, a set of loosely related "building blocks",
+ * and the Python code, which can generate C++ code using the pure classes,
+ * but with a significant degree of flexibility.
+ *
+ * The code user is expected to write a small python script that will
+ * properly define the DNS they are interested in running. That code will
+ * generate an executable that can then be run directly on the user's
+ * machine, or submitted to a queue on a cluster.
+ *
+ */
diff --git a/documentation/Makefile b/documentation/Makefile
deleted file mode 100644
index 6da2f7a60d704280c87a27e38572b387de2b6347..0000000000000000000000000000000000000000
--- a/documentation/Makefile
+++ /dev/null
@@ -1,192 +0,0 @@
-# Makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line.
-SPHINXOPTS =
-SPHINXBUILD = sphinx-build
-PAPER =
-BUILDDIR = _build
-
-# User-friendly check for sphinx-build
-ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
-$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
-endif
-
-# Internal variables.
-PAPEROPT_a4 = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-# the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
-
-help:
- @echo "Please use \`make <target>' where <target> is one of"
- @echo " html to make standalone HTML files"
- @echo " dirhtml to make HTML files named index.html in directories"
- @echo " singlehtml to make a single large HTML file"
- @echo " pickle to make pickle files"
- @echo " json to make JSON files"
- @echo " htmlhelp to make HTML files and a HTML help project"
- @echo " qthelp to make HTML files and a qthelp project"
- @echo " applehelp to make an Apple Help Book"
- @echo " devhelp to make HTML files and a Devhelp project"
- @echo " epub to make an epub"
- @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
- @echo " latexpdf to make LaTeX files and run them through pdflatex"
- @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
- @echo " text to make text files"
- @echo " man to make manual pages"
- @echo " texinfo to make Texinfo files"
- @echo " info to make Texinfo files and run them through makeinfo"
- @echo " gettext to make PO message catalogs"
- @echo " changes to make an overview of all changed/added/deprecated items"
- @echo " xml to make Docutils-native XML files"
- @echo " pseudoxml to make pseudoxml-XML files for display purposes"
- @echo " linkcheck to check all external links for integrity"
- @echo " doctest to run all doctests embedded in the documentation (if enabled)"
- @echo " coverage to run coverage check of the documentation (if enabled)"
-
-clean:
- rm -rf $(BUILDDIR)/*
-
-html:
- $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
- @echo
- @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-
-dirhtml:
- $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
- @echo
- @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
-
-singlehtml:
- $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
- @echo
- @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
-
-pickle:
- $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
- @echo
- @echo "Build finished; now you can process the pickle files."
-
-json:
- $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
- @echo
- @echo "Build finished; now you can process the JSON files."
-
-htmlhelp:
- $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
- @echo
- @echo "Build finished; now you can run HTML Help Workshop with the" \
- ".hhp project file in $(BUILDDIR)/htmlhelp."
-
-qthelp:
- $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
- @echo
- @echo "Build finished; now you can run "qcollectiongenerator" with the" \
- ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
- @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/bfps.qhcp"
- @echo "To view the help file:"
- @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/bfps.qhc"
-
-applehelp:
- $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
- @echo
- @echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
- @echo "N.B. You won't be able to view it unless you put it in" \
- "~/Library/Documentation/Help or install it in your application" \
- "bundle."
-
-devhelp:
- $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
- @echo
- @echo "Build finished."
- @echo "To view the help file:"
- @echo "# mkdir -p $$HOME/.local/share/devhelp/bfps"
- @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/bfps"
- @echo "# devhelp"
-
-epub:
- $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
- @echo
- @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
-
-latex:
- $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
- @echo
- @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
- @echo "Run \`make' in that directory to run these through (pdf)latex" \
- "(use \`make latexpdf' here to do that automatically)."
-
-latexpdf:
- $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
- @echo "Running LaTeX files through pdflatex..."
- $(MAKE) -C $(BUILDDIR)/latex all-pdf
- @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-latexpdfja:
- $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
- @echo "Running LaTeX files through platex and dvipdfmx..."
- $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
- @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-text:
- $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
- @echo
- @echo "Build finished. The text files are in $(BUILDDIR)/text."
-
-man:
- $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
- @echo
- @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
-
-texinfo:
- $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
- @echo
- @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
- @echo "Run \`make' in that directory to run these through makeinfo" \
- "(use \`make info' here to do that automatically)."
-
-info:
- $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
- @echo "Running Texinfo files through makeinfo..."
- make -C $(BUILDDIR)/texinfo info
- @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
-
-gettext:
- $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
- @echo
- @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
-
-changes:
- $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
- @echo
- @echo "The overview file is in $(BUILDDIR)/changes."
-
-linkcheck:
- $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
- @echo
- @echo "Link check complete; look for any errors in the above output " \
- "or in $(BUILDDIR)/linkcheck/output.txt."
-
-doctest:
- $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
- @echo "Testing of doctests in the sources finished, look at the " \
- "results in $(BUILDDIR)/doctest/output.txt."
-
-coverage:
- $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
- @echo "Testing of coverage in the sources finished, look at the " \
- "results in $(BUILDDIR)/coverage/python.txt."
-
-xml:
- $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
- @echo
- @echo "Build finished. The XML files are in $(BUILDDIR)/xml."
-
-pseudoxml:
- $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
- @echo
- @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
diff --git a/documentation/_static/api.rst b/documentation/_static/api.rst
deleted file mode 100644
index a1288bad8a875cff458e68ce13f7bcb85debed9c..0000000000000000000000000000000000000000
--- a/documentation/_static/api.rst
+++ /dev/null
@@ -1,44 +0,0 @@
-===
-API
-===
-
-
-----------
-bfps.tools
-----------
-
-.. automodule:: bfps.tools
- :members:
- :undoc-members:
- :show-inheritance:
-
-
------------------
-bfps.NavierStokes
------------------
-
-.. automodule:: bfps.NavierStokes
- :members:
- :undoc-members:
- :show-inheritance:
-
-
------------------
-bfps.FluidConvert
------------------
-
-.. automodule:: bfps.FluidConvert
- :members:
- :undoc-members:
- :show-inheritance:
-
-
-----------------
-bfps.FluidResize
-----------------
-
-.. automodule:: bfps.FluidResize
- :members:
- :undoc-members:
- :show-inheritance:
-
diff --git a/documentation/bandpass/notes0.rst b/documentation/bandpass/notes0.txt
similarity index 100%
rename from documentation/bandpass/notes0.rst
rename to documentation/bandpass/notes0.txt
diff --git a/documentation/_static/README.rst b/documentation/chapters/README.rst
similarity index 100%
rename from documentation/_static/README.rst
rename to documentation/chapters/README.rst
diff --git a/documentation/chapters/api.rst b/documentation/chapters/api.rst
new file mode 100644
index 0000000000000000000000000000000000000000..239ec0cac160c9a32fe5fe21d1eb1c208f664142
--- /dev/null
+++ b/documentation/chapters/api.rst
@@ -0,0 +1,53 @@
+===
+API
+===
+
+
+------------
+TurTLE
+------------
+
+.. automodule:: TurTLE
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+------------
+TurTLE.tools
+------------
+
+.. automodule:: TurTLE.tools
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+
+-----------
+TurTLE.TEST
+-----------
+
+.. automodule:: TurTLE.TEST
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+
+----------
+TurTLE.DNS
+----------
+
+.. automodule:: TurTLE.DNS
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+
+---------
+TurTLE.PP
+---------
+
+.. automodule:: TurTLE.PP
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
diff --git a/documentation/bandpass/bandpass.rst b/documentation/chapters/bandpass.rst
similarity index 96%
rename from documentation/bandpass/bandpass.rst
rename to documentation/chapters/bandpass.rst
index c23a8fbb1050da54f5b10a8bd9d1f11b87825cb9..400dffe56253418aa586782ab6a783f6e407ba4a 100644
--- a/documentation/bandpass/bandpass.rst
+++ b/documentation/chapters/bandpass.rst
@@ -1,14 +1,16 @@
--------------------------
+--------------------------------
TurTLE: Post-processing tutorial
--------------------------
+--------------------------------
Example problem:
----------------
Statistics of band-passed fields.
Please see
+
Drivas, T. D. and Johnson, P. L. and Lalescu, C. C. and Wilczek, M. Phys Rev Fluids 2 104603 (2017)
https://dx.doi.org/10.1103/PhysRevFluids.2.104603
+
The relevant files are `cpp/full_code/bandpass_stats.?pp`,
`TurTLE/PP.py` and `CMakeLists.txt` (the list of headers should be
updated).
diff --git a/documentation/_static/cpp.rst b/documentation/chapters/cpp.rst
similarity index 100%
rename from documentation/_static/cpp.rst
rename to documentation/chapters/cpp.rst
diff --git a/documentation/chapters/cpp_doxygen.rst b/documentation/chapters/cpp_doxygen.rst
new file mode 100644
index 0000000000000000000000000000000000000000..1e4246a162083d4508f590d7370d2d29028cd598
--- /dev/null
+++ b/documentation/chapters/cpp_doxygen.rst
@@ -0,0 +1,23 @@
+---
+CPP
+---
+
+.. doxygenclass:: kspace
+ :project: TurTLE
+ :members:
+
+.. doxygenclass:: field
+ :project: TurTLE
+ :members:
+
+.. doxygenclass:: code_base
+ :project: TurTLE
+ :members:
+
+.. doxygenclass:: direct_numerical_simulation
+ :project: TurTLE
+ :members:
+
+.. doxygenclass:: NSVE
+ :project: TurTLE
+ :members:
diff --git a/documentation/_static/development.rst b/documentation/chapters/development.rst
similarity index 100%
rename from documentation/_static/development.rst
rename to documentation/chapters/development.rst
diff --git a/documentation/_static/overview.rst b/documentation/chapters/overview.rst
similarity index 97%
rename from documentation/_static/overview.rst
rename to documentation/chapters/overview.rst
index 58af5653cab860961c71d057d92a21c9b99e6ddc..2ed997037f07026be50ee2976781c5eb7f861f92 100644
--- a/documentation/_static/overview.rst
+++ b/documentation/chapters/overview.rst
@@ -254,14 +254,14 @@ In brief the following takes place:
NavierStokes`` command.
2. reasonable DNS parameters are constructed from the command line
arguments.
- 4. ``c`` generates a parameter file ``<simname>.h5``, into which the
+ 3. ``c`` generates a parameter file ``<simname>.h5``, into which the
various parameters are written.
``c`` also generates the various datasets that the backend code
will write into (statistics and other stuff).
- 3. ``c`` writes a C++ file that is compiled and linked against
+ 4. ``c`` writes a C++ file that is compiled and linked against
``libbfps``.
- 4. ``c`` executes the C++ code using ``mpirun``.
- 5. the C++ code actually performs the DNS, and outputs various
+ 5. ``c`` executes the C++ code using ``mpirun``.
+ 6. the C++ code actually performs the DNS, and outputs various
results into the ``<simname>.h5`` file.
After the simulation is done, things are simpler.
diff --git a/documentation/conf.py b/documentation/conf.py.in
similarity index 78%
rename from documentation/conf.py
rename to documentation/conf.py.in
index 5fc2f86699b6f446001efb8dda00fab733c434a4..f9cf674535546b9bcf1a05e7daddd94bd7752374 100644
--- a/documentation/conf.py
+++ b/documentation/conf.py.in
@@ -1,8 +1,7 @@
-#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
-# bfps documentation build configuration file, created by
-# sphinx-quickstart on Thu Jan 21 20:53:27 2016.
+# TurTLE documentation build configuration file, created by
+# sphinx-quickstart on Sat Nov 16 10:17:05 2019.
#
# This file is execfile()d with the current directory set to its
# containing dir.
@@ -15,13 +14,16 @@
import sys
import os
-import shlex
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
-sys.path.insert(0, os.path.abspath('..'))
+sys.path.insert(0, os.path.abspath('@PROJECT_BINARY_DIR@/python'))
+
+breathe_projects = {
+ 'TurTLE' : os.path.abspath('@CMAKE_CURRENT_BINARY_DIR@/xml/'),
+ }
# -- General configuration ------------------------------------------------
@@ -32,13 +34,15 @@ sys.path.insert(0, os.path.abspath('..'))
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
+ 'breathe',
'sphinx.ext.autodoc',
'sphinx.ext.mathjax',
'sphinx.ext.viewcode',
+ 'sphinx.ext.imgconverter',
]
# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ['sphinx_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
@@ -52,47 +56,18 @@ source_suffix = '.rst'
master_doc = 'index'
# General information about the project.
-project = 'bfps'
-copyright = '2016, Cristian C Lalescu'
-author = 'Cristian C Lalescu'
-
-### package versioning
-# get current time
-import datetime
-import shutil
-import subprocess
-now = datetime.datetime.now()
-# obtain version
-try:
- git_branch = subprocess.check_output(['git',
- 'rev-parse',
- '--abbrev-ref',
- 'HEAD']).strip().split()[-1].decode()
- git_revision = subprocess.check_output(['git', 'rev-parse', 'HEAD']).strip()
- git_date = datetime.datetime.fromtimestamp(int(subprocess.check_output(['git', 'log', '-1', '--format=%ct']).strip()))
-except:
- git_revision = ''
- git_branch = ''
- git_date = now
-if git_branch == '':
- # there's no git available or something
- release = '{0:0>4}{1:0>2}{2:0>2}.{3:0>2}{4:0>2}{5:0>2}'.format(
- git_date.year, git_date.month, git_date.day,
- git_date.hour, git_date.minute, git_date.second)
-else:
- if (('develop' in git_branch) or
- ('feature' in git_branch) or
- ('bugfix' in git_branch)):
- release = subprocess.check_output(['git', 'describe', '--tags']).strip().decode()
- else:
- release = subprocess.check_output(['git', 'describe', '--tags']).strip().decode().split('-')[0]
+project = u'TurTLE'
+copyright = u'2019, TurTLE team'
+author = u'TurTLE team'
+
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
-# release is the full version, including alpha/beta/rc tags.
-# version is supposed to be the short X.Y version.
-version = release
+VERSION = '@TURTLE_VERSION@'
+version = VERSION
+# The full version, including alpha/beta/rc tags.
+release = VERSION
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
@@ -109,7 +84,7 @@ language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
-exclude_patterns = ['_build']
+exclude_patterns = ['sphinx_build']
# The reST default role (used for this markup: `text`) to use for all
# documents.
@@ -164,15 +139,15 @@ html_theme = 'alabaster'
# of the sidebar.
#html_logo = None
-# The name of an image file (within the static path) to use as favicon of the
-# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# The name of an image file (relative to this directory) to use as a favicon of
+# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ['@PROJECT_SOURCE_DIR@/documentation/_static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
@@ -222,8 +197,8 @@ html_static_path = ['_static']
# Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages:
-# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja'
-# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr'
+# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
+# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr'
#html_search_language = 'en'
# A dictionary with options for the search language support, empty by default.
@@ -235,7 +210,7 @@ html_static_path = ['_static']
#html_search_scorer = 'scorer.js'
# Output file base name for HTML help builder.
-htmlhelp_basename = 'bfpsdoc'
+htmlhelp_basename = 'TurTLEdoc'
# -- Options for LaTeX output ---------------------------------------------
@@ -247,7 +222,7 @@ latex_elements = {
#'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
-#'preamble': '',
+'preamble': '\usepackage{amssymb,amsmath,amsfonts}',
# Latex figure (float) alignment
#'figure_align': 'htbp',
@@ -257,8 +232,8 @@ latex_elements = {
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
- (master_doc, 'bfps.tex', 'bfps Documentation',
- 'Cristian C Lalescu', 'manual'),
+ (master_doc, 'TurTLE.tex', u'TurTLE Documentation',
+ u'TurTLE team', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
@@ -287,7 +262,7 @@ latex_documents = [
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
- (master_doc, 'bfps', 'bfps Documentation',
+ (master_doc, 'turtle', u'TurTLE Documentation',
[author], 1)
]
@@ -301,9 +276,9 @@ man_pages = [
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
- (master_doc, 'bfps', 'bfps Documentation',
- author, 'bfps', 'One line description of project.',
- 'Miscellaneous'),
+ (master_doc, 'TurTLE', u'TurTLE Documentation',
+ author, 'TurTLE', 'One line description of project.',
+ 'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
diff --git a/documentation/cpp/cpp_config b/documentation/cpp/cpp_config
index d740e899e959ac587767427b9bcf4f91e86c55ba..73726c8d5130f1e1c566483e7817ff464f263c77 100644
--- a/documentation/cpp/cpp_config
+++ b/documentation/cpp/cpp_config
@@ -238,7 +238,10 @@ TAB_SIZE = 4
# "Side Effects:". You can put \n's in the value part of an alias to insert
# newlines.
-ALIASES =
+# added rst and endrst as per https://exhale.readthedocs.io/en/latest/mastering_doxygen.html (retrieved 2019-11-16)
+# this is such that we can use reStructuredText within the documentation
+ALIASES = "rst=\verbatim embed:rst:leading-asterisk"
+ALIASES += "endrst=\endverbatim"
# This tag can be used to specify a number of word-keyword mappings (TCL only).
# A mapping has the form "name=value". For example adding "class=itcl::class"
@@ -790,7 +793,7 @@ WARN_LOGFILE =
# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
# Note: If this tag is empty the current directory is searched.
-INPUT = ../../cpp
+INPUT = ../cpp
# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1666,7 +1669,7 @@ EXTRA_SEARCH_MAPPINGS =
# If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output.
# The default value is: YES.
-GENERATE_LATEX = YES
+GENERATE_LATEX = NO
# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. If a
# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
@@ -1946,7 +1949,7 @@ MAN_LINKS = NO
# captures the structure of the code including all documentation.
# The default value is: NO.
-GENERATE_XML = NO
+GENERATE_XML = YES
# The XML_OUTPUT tag is used to specify where the XML pages will be put. If a
# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
@@ -2099,7 +2102,7 @@ INCLUDE_FILE_PATTERNS =
# recursively expanded use the := operator instead of the = operator.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
-PREDEFINED =
+PREDEFINED = IN_DOXYGEN
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
# tag can be used to specify a list of macro names that should be expanded. The
diff --git a/documentation/index.rst b/documentation/index.rst
index 9b0abc23648a08a9bd6692d2bc7651323c1b09d8..fc866054f00a40fcc9c07d1f0adfea7f8da81250 100644
--- a/documentation/index.rst
+++ b/documentation/index.rst
@@ -1,20 +1,23 @@
-.. bfps documentation master file, created by
- sphinx-quickstart on Thu Jan 21 20:53:27 2016.
+.. TurTLE documentation master file, created by
+ sphinx-quickstart on Sat Nov 16 10:17:05 2019.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
+Welcome to TurTLE's documentation!
+==================================
-Welcome to bfps's documentation!
-================================
+Contents:
.. toctree::
- :maxdepth: 2
-
- /_static/README
- /_static/overview
- /_static/development
- /_static/api
- /_static/cpp
+ :maxdepth: 4
+
+ chapters/README
+ chapters/overview
+ chapters/development
+ chapters/bandpass
+ chapters/api
+ chapters/cpp
+ chapters/cpp_doxygen
Indices and tables