reorganizes documentation

documentation/index.rst

@@ -12,14 +12,13 @@ Contents:
     :maxdepth: 4
 
     chapters/README
-    chapters/tutorial
-    chapters/development
-    chapters/bandpass
+    sphinx_static/overview
+    sphinx_static/convergence
+    sphinx_static/bandpass
+    sphinx_static/development
     chapters/api
     chapters/cpp_doxygen
 
-    sphinx_static/convergence
-
     sphinx_static/bibliography
 
 

documentation/chapters/bandpass.rst → documentation/sphinx_static/bandpass.rst

---------------------------------
-TurTLE: Post-processing tutorial
---------------------------------
+---------------------------------
+Tutorial: post-processing example
+---------------------------------
 
 Example problem:
 ----------------
 
 Statistics of band-passed fields.
-Please see
+Please see [drivas2017prf]_.
 
-    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
+The relevant files are :code:`cpp/full_code/bandpass_stats.?pp`,
+:code:`TurTLE/PP.py` and :code:`CMakeLists.txt` (the list of headers should be
 updated).
 
 Instructions in brief
@@ -20,21 +17,21 @@ Instructions in brief
 
 These are minimal instructions on how to create a generic post-processing tool,
 and they are roughly the procedure followed when writing the
-`cpp/full_code/bandpass_stats.?pp` files.
+:code:`cpp/full_code/bandpass_stats.?pp` files.
 
 1. Get code, install (please see README).
-2. In documentation/cpp use the command `doxygen cpp-config` to produce readable documentation for the code.
-   This provides also overview of class hierarchies, including the
-   `postprocess` class that should be used here.
+2. Have a look at the Doxygen generated documentation for the
+   ``postprocess`` class.
 3. Write down the explicit numerical task.
    Identify algorithms, parameters, check whether required functionality
    is available.
-4. Browse the documentation of the `postprocess` class.
 5. Write down simple outline of new code to implement within
-   `initialize`, `work_on_current_iteration` and `finalize`.
-6. Create a new `git` branch to work on, `feature/<mypptool>`.
-7. One option is to start from preexisting tools such as `get_rfields` and modify them accordingly.
-   In particular simple standard modifications must be made to the `PP.py` and `CmakeLists.txt` files.
+   ``initialize``, ``work_on_current_iteration`` and ``finalize``.
+6. Create a new :code:`git`` branch to work on, :code:`feature/<mypptool>`.
+7. One option is to start from preexisting tools such as :code:`get_rfields`
+   and modify them accordingly.
+   In particular simple standard modifications must be made to the :code:`PP.py`
+   and :code:`CmakeLists.txt` files.
 8. Design a test of the new functionality (possibly just a modification
    of an existing test as needed).
    Test should begin as a parameter I/O sanity check, and then grow as

documentation/sphinx_static/bibliography.rst

@@ -29,3 +29,6 @@ Bibliography
     `J. Fluid Mech. 847, R2 (2018)
     <https://doi.org/10.1017/jfm.2018.381>`_
 
+.. [drivas2017prf] Drivas, T. D. and Johnson, P. L. and Lalescu, C. C. and Wilczek, M.
+    *Large-scale sweeping of small-scale eddies in turbulence: A filtering approach*.
+    `Phys Rev Fluids 2 104603 (2017) <https://dx.doi.org/10.1103/PhysRevFluids.2.104603>`_

documentation/chapters/development.rst → documentation/sphinx_static/development.rst

@@ -20,7 +20,7 @@ In principle, if you use :mod:`TurTLE` and you've created children of the
 the ``MAJOR`` version changes.
 
 There are 2 main branches, ``master`` and ``develop``.
-``setup.py`` will call ``git`` to read in the ``VERSION``: it will get the
+``CMake`` will essentially call ``git`` to read in the ``VERSION``: it will get the
 latest available tag.
 If the active branch name contains either of the strings ``develop``,
 ``feature`` or ``bugfix``, then the full output of ``git describe --tags``
@@ -56,5 +56,6 @@ projects, these may change.
 Code testing
 ------------
 
-We use CTest for testing `TurTLE`.
+We use CTest for testing `TurTLE`, and the ``.gitlab-ci.yml`` script
+calls CTest.
 

documentation/sphinx_static/hs.rst

+Tutorial: hydrodynamic similarity
+---------------------------------
+
+run turtle twice with different values of parameters.
+
+
+first run with default parameters
+
+.. code:: bash
+    
+    turtle NSE --simname test_1 \
+        --dkx 1.0 \
+        --dky 1.0 \
+        --dkz 1.0 \
+        --nu 0.1 \
+        --injection_rate 0.4 \
+
+
+second, scale parameters by 2
+
+.. code:: bash
+
+    turtle NSE --simname test_2 \
+        --dkx 0.5 \
+        --dky 0.5 \
+        --dkz 0.5 \
+        --nu 0.1*factor \ #FIXME
+        --injection_rate 0.4*forcing_factor #FIXME
+
+
+afterwards, execute the following python code:
+
+.. code:: python
+
+    c1 = NSReader(simname = 'test_1')
+    c1 = NSReader(simname = 'test_2')
+    u1 = c1.read_cvelocity(iter1)
+    u2 = c2.read_cvelocity(iter1)
+
+    diff = np.abs(u1 - u2*vel_factor) / np.abs(u1) # take care of 0s
+
+    assert(diff.max() < 1e-5)
+

documentation/chapters/tutorial.rst → documentation/sphinx_static/overview.rst

-=====================
-Overview and Tutorial
-=====================
+========
+Overview
+========
 
 ----------------
 General comments