From 0c2251be8518f66f26dbf61a2fc3142c1eb9c740 Mon Sep 17 00:00:00 2001
From: Cristian C Lalescu <Cristian.Lalescu@mpcdf.mpg.de>
Date: Tue, 1 Feb 2022 13:06:20 +0100
Subject: [PATCH 01/24] generates parent document for doxygen/sphinx
---
.gitlab-ci.yml | 4 ++--
CMakeLists.txt | 18 ++++++++++++++
documentation/conf.py.in | 2 +-
documentation/index.html.in | 38 ++++++++++++++++++++++++++++++
documentation/merge_doc_html.sh.in | 12 ++++++++++
5 files changed, 71 insertions(+), 3 deletions(-)
create mode 100644 documentation/index.html.in
create mode 100644 documentation/merge_doc_html.sh.in
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 10776184..bcc9d784 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -202,8 +202,8 @@ pages:
artifacts:
paths:
- public
- only:
- - tags
+# only:
+# - tags
tags:
- docker
needs:
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 627474c6..b983626e 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -29,6 +29,8 @@ cmake_policy(VERSION 3.12)
project(TurTLE)
+string(TIMESTAMP BUILD_DATE "%Y-%m-%d")
+
#####################################################################################
## Python and version
@@ -172,6 +174,22 @@ if (SPHINX_FOUND)
"${PROJECT_SOURCE_DIR}/documentation"
"${SPHINX_LATEX_DIR}"
COMMENT "Building LaTeX documentation with Sphinx")
+
+ if (DOXYGEN_FOUND)
+ set(FULL_DOC_BUILD_DIR "${CMAKE_CURRENT_BINARY_DIR}/public")
+ configure_file(
+ "${PROJECT_SOURCE_DIR}/documentation/index.html.in"
+ "${CMAKE_CURRENT_BINARY_DIR}/doc_full_index.html")
+ configure_file(
+ "${PROJECT_SOURCE_DIR}/documentation/merge_doc_html.sh.in"
+ "${CMAKE_CURRENT_BINARY_DIR}/merge_doc_html.sh")
+
+ add_custom_target(doc_html_full
+ COMMAND sh merge_doc_html.sh
+ DEPENDS doc_doxygen doc_html
+ WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+ COMMENT "Merging Doxygen and Sphinx HTML documentation")
+ endif()
else (SPHINX_FOUND)
message("Sphinx needs to be installed to generate the full documentation")
endif (SPHINX_FOUND)
diff --git a/documentation/conf.py.in b/documentation/conf.py.in
index c05020c9..89e40fed 100644
--- a/documentation/conf.py.in
+++ b/documentation/conf.py.in
@@ -22,7 +22,7 @@ breathe_projects = {
# -- Project information -----------------------------------------------------
project = 'TurTLE'
-copyright = '2021, TurTLE team'
+copyright = '2022, TurTLE team'
author = 'TurTLE team'
# The full version, including alpha/beta/rc tags
diff --git a/documentation/index.html.in b/documentation/index.html.in
new file mode 100644
index 00000000..fa9500bc
--- /dev/null
+++ b/documentation/index.html.in
@@ -0,0 +1,38 @@
+<html>
+ <title>TurTLE v@TURTLE_VERSION@</title>
+ <h1>TurTLE v@TURTLE_VERSION@</h1>
+ <p>
+ Thank you for browsing the documentation of <a href="https://gitlab.mpcdf.mpg.de/TurTLE/turtle">TurTLE</a>.
+ </p>
+ <p>
+ TurTLE stands for "Turbulence Tools: Lagrangian and Eulerian" and it is
+ developed and maintained by the Wilczek group at the
+ <a href="https://www.ds.mpg.de/wilczek">Max Planck
+ Institute for Dynamics and Self-Organization</a>
+ and the
+ <a href="https://www.wilczek.physik.uni-bayreuth.de/en/team/index.html">
+ University of Bayreuth</a>
+ in collaboration with the Application Support Group of the Max Planck
+ Computing and Data Facility.
+ </p>
+ <p>
+ TurTLE is a framework for
+ pseudo-spectral simulations of turbulence, with a highly optimized particle tracking method.
+ It consists of a C++ core library, as well as a Python "wrapper" library.
+ </p>
+ <p>
+ The documentation consists of two parts:
+ </p>
+ <ul>
+ <li>
+ <a href="doxygen_html/index.html">HTML C++</a> documentation.
+ Full Doxygen output, including, e.g., class index and inheritance graphs.</li>
+ <li>
+ <a href="sphinx_html/index.html">HTML manual</a> generated with Sphinx.
+ This contains tutorials, the Python library documentation, and part of the C++ Doxygen output.
+ </li>
+ </ul>
+ <footer>
+ Last updated @BUILD_DATE@.
+ </footer>
+</html>
diff --git a/documentation/merge_doc_html.sh.in b/documentation/merge_doc_html.sh.in
new file mode 100644
index 00000000..fa8176f3
--- /dev/null
+++ b/documentation/merge_doc_html.sh.in
@@ -0,0 +1,12 @@
+#! /usr/bin/env bash
+
+mkdir -p public
+cp -r \
+ @CMAKE_CURRENT_BINARY_DIR@/html \
+ @CMAKE_CURRENT_BINARY_DIR@/public/doxygen_html
+cp -r \
+ @CMAKE_CURRENT_BINARY_DIR@/sphinx_html \
+ @CMAKE_CURRENT_BINARY_DIR@/public/sphinx_html
+cp \
+ @CMAKE_CURRENT_BINARY_DIR@/doc_full_index.html \
+ @CMAKE_CURRENT_BINARY_DIR@/public/index.html
--
GitLab
From 2526efc77eb3eed2c6fea3da72989ff3cd6fbf71 Mon Sep 17 00:00:00 2001
From: Cristian C Lalescu <Cristian.Lalescu@mpcdf.mpg.de>
Date: Tue, 1 Feb 2022 14:13:52 +0100
Subject: [PATCH 02/24] updates gitlab ci page step
---
.gitlab-ci.yml | 1 +
1 file changed, 1 insertion(+)
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index bcc9d784..e802a4cc 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -199,6 +199,7 @@ pages:
- mv build-doc/html public/
- mv build-doc/sphinx_html public/
#- mv TurTLE_manual.pdf public/
+ - mv build-doc/doc_full_index.html public/
artifacts:
paths:
- public
--
GitLab
From 433f69212603a5e233161d7989efe233e4ec23c1 Mon Sep 17 00:00:00 2001
From: Cristian C Lalescu <Cristian.Lalescu@mpcdf.mpg.de>
Date: Tue, 1 Feb 2022 14:39:53 +0100
Subject: [PATCH 03/24] updates documentation deployment
---
.gitlab-ci.yml | 9 ++++-----
1 file changed, 4 insertions(+), 5 deletions(-)
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index e802a4cc..985dfd49 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -158,8 +158,7 @@ build-doc:
- pip install breathe
- yum -y install gd
- cmake .. -DNDEBUG=OFF -DTIMING_OUTPUT=OFF
- - make VERBOSE=1 doc_doxygen
- - make VERBOSE=1 doc_html
+ - make VERBOSE=1 doc_html_full
#- make VERBOSE=1 doc_latex
tags:
- docker
@@ -196,10 +195,10 @@ pages:
- build-doc
script:
- mkdir public
- - mv build-doc/html public/
- - mv build-doc/sphinx_html public/
+ - mv build-doc/html public/doxygen_html
+ - mv build-doc/sphinx_html public/sphinx_html
#- mv TurTLE_manual.pdf public/
- - mv build-doc/doc_full_index.html public/
+ - mv build-doc/doc_full_index.html public/index.html
artifacts:
paths:
- public
--
GitLab
From f200bb04732d08cf5b12a3ce16c3ada39efd6c4f Mon Sep 17 00:00:00 2001
From: Cristian C Lalescu <Cristian.Lalescu@mpcdf.mpg.de>
Date: Tue, 1 Feb 2022 14:47:25 +0100
Subject: [PATCH 04/24] updates documentation link
---
.gitlab-ci.yml | 2 +-
README.rst | 6 ++----
2 files changed, 3 insertions(+), 5 deletions(-)
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 985dfd49..975afa0f 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -153,7 +153,7 @@ build-doc:
- *load_modules
- mkdir build-doc
- cd build-doc
- - module load gcc graphviz doxygen
+ - module load git gcc graphviz doxygen
- *export_GCC_compilers
- pip install breathe
- yum -y install gd
diff --git a/README.rst b/README.rst
index bf605a97..3d457c84 100644
--- a/README.rst
+++ b/README.rst
@@ -39,10 +39,8 @@ the use of the Python wrapper.
Background and documentation
----------------------------
-Partial documentation is available at
-http://TurTLE.pages.mpcdf.de/turtle/sphinx_html; the C++ API is
-described at http://TurTLE.pages.mpcdf.de/turtle/html
-(`doxygen`-generated).
+Please find Up-to-date documentation at
+http://TurTLE.pages.mpcdf.de/turtle/index.html.
Authors
-------
--
GitLab
From fe4180b1a0b883d49d41e76a2d5075e59e89ee89 Mon Sep 17 00:00:00 2001
From: Cristian C Lalescu <Cristian.Lalescu@mpcdf.mpg.de>
Date: Tue, 1 Feb 2022 20:20:43 +0100
Subject: [PATCH 05/24] bump static version script
---
configure_python.sh | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/configure_python.sh b/configure_python.sh
index 4356bef4..bc38e9ee 100644
--- a/configure_python.sh
+++ b/configure_python.sh
@@ -3,8 +3,8 @@
set -e
cp host_info.py TurTLE/
-sed "s/@TURTLE_VERSION_LONG@/3.14/" setup.py.in > setup.py
-sed "s/@TURTLE_VERSION_LONG@/3.14/" TurTLE/__init__.py.in > TurTLE/__init__.py.tmp
+sed "s/@TURTLE_VERSION_LONG@/3.15/" setup.py.in > setup.py
+sed "s/@TURTLE_VERSION_LONG@/3.15/" TurTLE/__init__.py.in > TurTLE/__init__.py.tmp
sed "s/@CMAKE_INSTALL_DIR@/UNAVAILABLE_FOR_PURE_PYTHON_INSTALLS/" TurTLE/__init__.py.tmp > TurTLE/__init__.py
rm TurTLE/__init__.py.tmp
--
GitLab
From d1a8b8fe0faf4c4f6541747aaa540b17b06f47bb Mon Sep 17 00:00:00 2001
From: Cristian C Lalescu <Cristian.Lalescu@mpcdf.mpg.de>
Date: Tue, 1 Feb 2022 21:06:01 +0100
Subject: [PATCH 06/24] fixes local documentation build
---
documentation/merge_doc_html.sh.in | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/documentation/merge_doc_html.sh.in b/documentation/merge_doc_html.sh.in
index fa8176f3..99f13516 100644
--- a/documentation/merge_doc_html.sh.in
+++ b/documentation/merge_doc_html.sh.in
@@ -1,12 +1,12 @@
#! /usr/bin/env bash
mkdir -p public
-cp -r \
+rsync --archive \
@CMAKE_CURRENT_BINARY_DIR@/html \
- @CMAKE_CURRENT_BINARY_DIR@/public/doxygen_html
-cp -r \
+ @CMAKE_CURRENT_BINARY_DIR@/public/
+rsync --archive \
@CMAKE_CURRENT_BINARY_DIR@/sphinx_html \
- @CMAKE_CURRENT_BINARY_DIR@/public/sphinx_html
+ @CMAKE_CURRENT_BINARY_DIR@/public/
cp \
@CMAKE_CURRENT_BINARY_DIR@/doc_full_index.html \
@CMAKE_CURRENT_BINARY_DIR@/public/index.html
--
GitLab
From 24173cbd2172c09217d6541552cc0bbd86aee7b6 Mon Sep 17 00:00:00 2001
From: Cristian C Lalescu <Cristian.Lalescu@mpcdf.mpg.de>
Date: Tue, 1 Feb 2022 21:06:16 +0100
Subject: [PATCH 07/24] tweaks README
---
README.rst | 33 ++++++++++++++++++++-------------
1 file changed, 20 insertions(+), 13 deletions(-)
diff --git a/README.rst b/README.rst
index 3d457c84..e0c80980 100644
--- a/README.rst
+++ b/README.rst
@@ -39,7 +39,7 @@ the use of the Python wrapper.
Background and documentation
----------------------------
-Please find Up-to-date documentation at
+Please find up-to-date documentation at
http://TurTLE.pages.mpcdf.de/turtle/index.html.
Authors
@@ -52,7 +52,7 @@ Computing and Data Facility.
TurTLE contains contributions from:
- .. include:: AUTHORS
+.. include:: AUTHORS
.. _sec-installation:
@@ -94,14 +94,14 @@ are able to find it), as well as an installation of Python 3.
The list is a work in progress, please contact us
(Cristian.Lalescu@mpcdf.mpg.de) if the procedure fails at any step of the
process.
-We recommend to first go through the instructions in full, and only
+We recommend to first read the instructions in full, and only
afterwards starting to execute the individual steps.
**Creating a virtual environment**
We recommend creating a virtual environment for TurTLE. To do this,
choose an installation location :code:`<INSTALL_LOC>` on a local fast partition
-(Under unix systems, this could be e.g. `~/.local`) and a name for the
+(under unix systems, this could be e.g. `~/.local`) and a name for the
environment :code:`<VENV_NAME>` (e.g. `turtle-production`).
To create the virtual environment, execute:
@@ -117,19 +117,21 @@ environments, please see https://docs.python-guide.org/dev/virtualenvs/.
TurTLE has the following requirements:
-- C/C++ MPI compiler of your choice
+- C/C++ compiler of your choice
+
+- MPI
- Python 3
- FFTW version >= 3.3.4
-- HDF5 version >= 1.8. **Important**: must be compiled with the option "--enable-parallel"
+- HDF5 version >= 1.8. **Important**: must be compiled with the option :code:`--enable-parallel`
- cmake version > 3.12
We will assume you already have a working MPI compiler and an
installation of Python 3. For the other requirements, we provide
-installation instructions in the following. We recommend installing
+installation instructions. We recommend installing
them on a local fast partition. In the following, we refer to their
locations as :code:`<FFTW_DIR>`, :code:`<HDF5_DIR>` and
:code:`<CMAKE_DIR>`. You may choose to install the requirements into
@@ -138,9 +140,9 @@ equal to :code:`<TURTLE_DIR>`.
- **FFTW**
Download latest version from http://www.fftw.org/.
- To compile and install it in custom location :code:`<FFTW_DIR>`,
- execute the following commands in order, feel free to customize
- optimisation flags for your own computer (see
+ To compile and install it in the custom location :code:`<FFTW_DIR>`,
+ execute the following commands in order (feel free to customize
+ optimisation flags for your own computer, see
http://www.fftw.org/fftw3_doc/Installation-on-Unix.html):
.. code:: bash
@@ -169,8 +171,8 @@ equal to :code:`<TURTLE_DIR>`.
make
make install
- Since TurTLE is using parallel I/O, HDF5 needs to be compiled with
- the "--enable-parallel" flag.
+ The :code:`--enable-parallel` flag is required because TurTLE uses
+ parallel I/O.
..
TurTLE will try to find HDF5 using the regular FindHDF5, which
@@ -202,6 +204,10 @@ equal to :code:`<TURTLE_DIR>`.
git clone git@gitlab.mpcdf.mpg.de:TurTLE/turtle.git
+ Alternatively, you may visit the website
+ https://gitlab.mpcdf.mpg.de/TurTLE/turtle
+ and download the source manually.
+
2. Execute
.. code:: bash
@@ -340,7 +346,8 @@ Comments
details.
* particles: initialization of multistep solvers is done with lower
- order methods, so direct convergence tests will fail.
+ order methods, so direct convergence tests will fail (see the
+ "convergence test" tutorial for more information).
* code is used mainly with Python 3.5 and later, and it is not tested at
all with Python 2.x
--
GitLab
From e9a41f47923daf3ba278692f9f9b208a61ee75c0 Mon Sep 17 00:00:00 2001
From: Cristian C Lalescu <Cristian.Lalescu@mpcdf.mpg.de>
Date: Wed, 2 Feb 2022 06:43:17 +0100
Subject: [PATCH 08/24] fixes rsync usage
---
documentation/merge_doc_html.sh.in | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/documentation/merge_doc_html.sh.in b/documentation/merge_doc_html.sh.in
index 99f13516..8958a3e8 100644
--- a/documentation/merge_doc_html.sh.in
+++ b/documentation/merge_doc_html.sh.in
@@ -1,9 +1,9 @@
#! /usr/bin/env bash
-mkdir -p public
+mkdir -p public/doxygen_html
rsync --archive \
- @CMAKE_CURRENT_BINARY_DIR@/html \
- @CMAKE_CURRENT_BINARY_DIR@/public/
+ @CMAKE_CURRENT_BINARY_DIR@/html/ \
+ @CMAKE_CURRENT_BINARY_DIR@/public/doxygen_html
rsync --archive \
@CMAKE_CURRENT_BINARY_DIR@/sphinx_html \
@CMAKE_CURRENT_BINARY_DIR@/public/
--
GitLab
From 890589baa7b8378f8c7662590eb708d387c840f5 Mon Sep 17 00:00:00 2001
From: Cristian C Lalescu <Cristian.Lalescu@mpcdf.mpg.de>
Date: Wed, 2 Feb 2022 06:43:25 +0100
Subject: [PATCH 09/24] updates overview
---
cpp/kspace.cpp | 2 +-
documentation/chapters/tutorial.rst | 78 ++++++++++----------
documentation/sphinx_static/bibliography.rst | 10 +++
3 files changed, 52 insertions(+), 38 deletions(-)
diff --git a/cpp/kspace.cpp b/cpp/kspace.cpp
index 369db623..b1f40ae4 100644
--- a/cpp/kspace.cpp
+++ b/cpp/kspace.cpp
@@ -501,7 +501,7 @@ int kspace<be, dt>::filter(
* the large scales is approximately the same (within the inertial range)
* independently of the shape of the filter.
*
- * This was done by hand, see [INSERT CITATION HERE] for details, with the
+ * This was done by hand, see [lalescu2018jfm]_ for details, with the
* results:
*
* \f[
diff --git a/documentation/chapters/tutorial.rst b/documentation/chapters/tutorial.rst
index 4ee154cc..b8cb1d1b 100644
--- a/documentation/chapters/tutorial.rst
+++ b/documentation/chapters/tutorial.rst
@@ -19,13 +19,10 @@ With TurTLE, the desire is to identify core functionality that should be
implemented in a library.
The core library can then be used by many problem-specific codes.
-In this sense, the structuring of the code-base is non-standard.
-The core functionality is implemented in C++ (classes useful for
-describing working with fields or sets of particles), while a Python3
-wrapper is used for generating "main" programmes to be linked against
-the core library.
-The core library uses a hybrid MPI/OpenMP approach for parallelization, and the Python3 wrapper
-compiles this core library when being installed.
+The core functionality is implemented in C++, while a Python3
+wrapper is typically used for generating initial conditions and
+light-weight post-processing.
+The core library uses a hybrid MPI/OpenMP approach for parallelization.
Python3 "wrapper"
-----------------
@@ -36,13 +33,6 @@ launching jobs and postprocessing data.
Classes defined in the Python3 package can be used to generate executable
codes, compile/launch them, and then for accessing and postprocessing
data with a full Python3 environment.
-
-Code generation is quite straightforward, with C++ code snippets handled
-as strings in the Python3 code, such that they can be combined in
-different ways.
-
-Once a "main" file has been written, it is compiled and linked against
-the core library.
Depending on machine-specific settings, the code can then be launched
directly, or job scripts appropriate for queueing systems are generated
and submitted.
@@ -50,16 +40,22 @@ and submitted.
C++ core library
----------------
-TurTLE has a hierarchy of classes that provide prototypes for three basic tasks: perform a DNS, post-process existing data or test arbitrary functionality.
-As a guiding principle, the distinct tasks and concepts involved in the numerical simulation in TurTLE are isolated as much as possible, which simplifies the development of extensions.
-
-There are two types of simple objects.
-Firstly, an abstract class encapsulates three elements: generic *initialization*, *do work* and *finalization* functionality.
-Secondly, essential data structures (i.e. fields, sets of particles) and associated functionality (i.e. I/O) are provided by "building block"-classes.
-The solver then consists of a specific arrangement of the building blocks.
-
-The heterogeneous TurTLE development team benefits from the separation of generic functionality from building blocks:
-TurTLE is naturally well-suited to the distribution of conceptually distinct work, in particular fully isolating projects such as, e.g., "implement new numerical method" from "optimize the computation of field statistics with OpenMP".
+As already stated, TurTLE's main goal is to facilitate novel research
+avenues.
+To this end, there are two types of simple objects.
+Firstly, children of an abstract class that encapsulates three elements: generic
+*initialization*, *do work* and *finalization* functionality.
+Secondly, essential data structures (i.e. fields, sets of particles) and
+associated functionality (i.e. I/O) are provided by "building block"-classes.
+Each TurTLE "solver" then consists of a specific arrangement of the building
+blocks.
+
+The heterogeneous TurTLE development team benefits from the separation of
+generic functionality from building blocks:
+TurTLE is naturally well-suited to the distribution of conceptually distinct
+work, in particular fully isolating projects such as, e.g., "implement new
+numerical method" from "optimize the computation of field statistics with
+OpenMP".
---------
Equations
@@ -67,15 +63,16 @@ Equations
The code uses a fairly standard pseudo-spectral algorithm to solve fluid
equations.
-The incompressible Navier Stokes equations in velocity form are as
-follows:
+The incompressible Navier Stokes equations in velocity form (see the
+`NSE` C++ class) are as follows:
.. math::
\partial_t \mathbf{u} + \mathbf{u} \cdot \nabla \mathbf{u} =
- \nabla p + \nu \Delta \mathbf{u} + \mathbf{f}
-``TurTLE`` solves the vorticity formulation of these equations:
+TurTLE also solves the vorticity formulation of these equations (see the
+`NSVE` C++ class):
.. math::
\partial_t \mathbf{\omega} +
@@ -155,9 +152,9 @@ wavenumbers:
kval[..., 1] = ky[:, None, None]
kval[..., 2] = kz[None, :, None]
---------
-Tutorial
---------
+----------------
+Tutorial: basics
+----------------
First DNS
---------
@@ -179,6 +176,7 @@ This launches a simulation in the current folder, with the simulation
name "test".
The simulation itself should not take more than a few seconds, since
this is just a :math:`32^3` simulation run for 8 iterations.
+The prior compilation step may take a bit longer.
First thing you can do afterwards is open a python console, and type
the following:
@@ -237,8 +235,9 @@ In brief the following takes place:
various parameters are written.
``c`` also generates the various datasets that the backend code
will write into (statistics).
- 4. ``c`` writes a C++ file that is compiled and linked against
- ``libTurTLE``.
+ 4. ``c`` writes a simple C++ file that is compiled and linked against
+ ``libTurTLE`` (to be specific, it calls the :code:`main_code`
+ function defined in :code:`cpp/full_code/main_code.hpp`).
5. ``c`` executes the C++ code using the appropriate launcher (e.g. ``mpiexec``).
6. the C++ code actually performs the DNS, and outputs various
results into the ``<simname>.h5`` file. It also outputs the final
@@ -251,11 +250,15 @@ file, and the dataset names should be reasonably easy to interpret, so
custom postprocessing codes can easily be generated.
---------------------
-Scaling tests.
---------------------
+-------------
+Scaling tests
+-------------
+
+Our own scaling tests are reported in [lalescu2021arXiv]_.
Initial scaling data is available at (url coming soon).
+For now you need to run a preliminary DNS of 8192 iterations using a
+grid of :math:`128^3` points.
Please copy the files to the location `TURTLE_FIELD_DATABASE`.
Separately, please recompile TurTLE with the `TIMING_OUTPUT` cmake
@@ -272,7 +275,8 @@ Afterwards, please run variations of the following command:
--src-wd ${TURTLE_FIELD_DATABASE} \
--src-iteration 8192
-Available iterations for
+..
+ Available iterations for
- * n = 128: 8192
+ * n = 128: 8192
diff --git a/documentation/sphinx_static/bibliography.rst b/documentation/sphinx_static/bibliography.rst
index 1b90b082..df85f6a3 100644
--- a/documentation/sphinx_static/bibliography.rst
+++ b/documentation/sphinx_static/bibliography.rst
@@ -19,3 +19,13 @@ Bibliography
J. Comput. Phys.
**229**, 5862-5869, 2010
+.. [lalescu2021arXiv] C. C. Lalescu, B. Bramas, M. Rampp and M. Wilczek
+ *An Efficient Particle Tracking Algorithm for Large-Scale Parallel
+ Pseudo-Spectral Simulations of Turbulence*.
+ `arXiv 2107.01104 (2021) <https://arxiv.org/abs/2107.01104>`_
+
+.. [lalescu2018jfm] C. C. Lalescu and M. Wilczek
+ *Acceleration statistics of tracer particles in filtered turbulent fields*.
+ `J. Fluid Mech. 847, R2 (2018)
+ <https://doi.org/10.1017/jfm.2018.381>`_
+
--
GitLab
From a150845ed07a7a4b0377723b226bf02a16d466f8 Mon Sep 17 00:00:00 2001
From: Cristian C Lalescu <Cristian.Lalescu@mpcdf.mpg.de>
Date: Wed, 2 Feb 2022 09:14:10 +0100
Subject: [PATCH 10/24] reorganizes documentation
---
documentation/chapters/bandpass.rst | 42 ------------------
documentation/index.rst | 9 ++--
documentation/sphinx_static/bandpass.rst | 39 +++++++++++++++++
documentation/sphinx_static/bibliography.rst | 3 ++
.../{chapters => sphinx_static}/cpp.rst | 0
.../development.rst | 5 ++-
documentation/sphinx_static/hs.rst | 43 +++++++++++++++++++
.../overview.rst} | 6 +--
8 files changed, 95 insertions(+), 52 deletions(-)
delete mode 100644 documentation/chapters/bandpass.rst
create mode 100644 documentation/sphinx_static/bandpass.rst
rename documentation/{chapters => sphinx_static}/cpp.rst (100%)
rename documentation/{chapters => sphinx_static}/development.rst (93%)
create mode 100644 documentation/sphinx_static/hs.rst
rename documentation/{chapters/tutorial.rst => sphinx_static/overview.rst} (99%)
diff --git a/documentation/chapters/bandpass.rst b/documentation/chapters/bandpass.rst
deleted file mode 100644
index 400dffe5..00000000
--- a/documentation/chapters/bandpass.rst
+++ /dev/null
@@ -1,42 +0,0 @@
---------------------------------
-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).
-
-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.
-
-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.
-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.
-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
- the required functionality is implemented.
-
diff --git a/documentation/index.rst b/documentation/index.rst
index 7788a2f2..36c60cd3 100644
--- a/documentation/index.rst
+++ b/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
diff --git a/documentation/sphinx_static/bandpass.rst b/documentation/sphinx_static/bandpass.rst
new file mode 100644
index 00000000..7c892160
--- /dev/null
+++ b/documentation/sphinx_static/bandpass.rst
@@ -0,0 +1,39 @@
+---------------------------------
+Tutorial: post-processing example
+---------------------------------
+
+Example problem:
+----------------
+
+Statistics of band-passed fields.
+Please see [drivas2017prf]_.
+
+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
+---------------------
+
+These are minimal instructions on how to create a generic post-processing tool,
+and they are roughly the procedure followed when writing the
+:code:`cpp/full_code/bandpass_stats.?pp` files.
+
+1. Get code, install (please see README).
+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.
+5. Write down simple outline of new code to implement within
+ ``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
+ the required functionality is implemented.
+
diff --git a/documentation/sphinx_static/bibliography.rst b/documentation/sphinx_static/bibliography.rst
index df85f6a3..a2c70575 100644
--- a/documentation/sphinx_static/bibliography.rst
+++ b/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>`_
diff --git a/documentation/chapters/cpp.rst b/documentation/sphinx_static/cpp.rst
similarity index 100%
rename from documentation/chapters/cpp.rst
rename to documentation/sphinx_static/cpp.rst
diff --git a/documentation/chapters/development.rst b/documentation/sphinx_static/development.rst
similarity index 93%
rename from documentation/chapters/development.rst
rename to documentation/sphinx_static/development.rst
index 5f18cf1f..7dc9836b 100644
--- a/documentation/chapters/development.rst
+++ b/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.
diff --git a/documentation/sphinx_static/hs.rst b/documentation/sphinx_static/hs.rst
new file mode 100644
index 00000000..3978ebb7
--- /dev/null
+++ b/documentation/sphinx_static/hs.rst
@@ -0,0 +1,43 @@
+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)
+
diff --git a/documentation/chapters/tutorial.rst b/documentation/sphinx_static/overview.rst
similarity index 99%
rename from documentation/chapters/tutorial.rst
rename to documentation/sphinx_static/overview.rst
index b8cb1d1b..2c640529 100644
--- a/documentation/chapters/tutorial.rst
+++ b/documentation/sphinx_static/overview.rst
@@ -1,6 +1,6 @@
-=====================
-Overview and Tutorial
-=====================
+========
+Overview
+========
----------------
General comments
--
GitLab
From 33f7c916acb0639ea48677fbe9716516e91a6707 Mon Sep 17 00:00:00 2001
From: Cristian C Lalescu <Cristian.Lalescu@mpcdf.mpg.de>
Date: Wed, 2 Feb 2022 10:26:37 +0100
Subject: [PATCH 11/24] adds crosslinks to doxygen
---
cpp/full_code/NSE.cpp | 22 +---
documentation/chapters/cpp_doxygen.rst | 128 ++++++++++++++-----
documentation/sphinx_static/bibliography.rst | 5 +
3 files changed, 107 insertions(+), 48 deletions(-)
diff --git a/cpp/full_code/NSE.cpp b/cpp/full_code/NSE.cpp
index fac9a0b3..2e1c0b68 100644
--- a/cpp/full_code/NSE.cpp
+++ b/cpp/full_code/NSE.cpp
@@ -407,7 +407,7 @@ int NSE<rnumber>::Euler_step(void)
/** \brief Time step with Shu Osher method
*
* The Navier Stokes equations are integrated with a
- * third-order Runge-Kutta method \cite shu1988jcp, which is an explicit
+ * third-order Runge-Kutta method [shu1988jcp]_, which is an explicit
* Runge-Kutta method with the Butcher tableau
*
* | | | | |
@@ -417,23 +417,15 @@ int NSE<rnumber>::Euler_step(void)
* | 1/2 | 1/4 | 1/4 | |
* | | 1/6 | 1/6 | 2/3 |
*
- * In addition to the stability properties described in \cite shu1988jcp, this method has the advantage that it is memory-efficient, requiring only two additional field allocations, as can be seen from
+ * In addition to the stability properties described in [shu1988jcp]_, this method has the advantage that it is memory-efficient, requiring only two additional field allocations, as can be seen from
* \f{eqnarray*}{
- * \hat{\bs w}_1(\bs k) &= {\hat{\bs u}}(\bs k, t)e^{-\nu k^2 h} + h \NL[\hat{\bs u}(\bs k, t)]e^{-\nu k^2 h}, \\
- * \hat{\bs w}_2(\bs k) &= \frac{3}{4}\hat{\bs u}( \bs k, t)e^{-\nu k^2 h/2}
+ * \hat{\boldsymbol w}_1(\boldsymbol k) &= {\hat{\boldsymbol u}}(\boldsymbol k, t)e^{-\nu k^2 h} + h \textrm{NL}[\hat{\boldsymbol u}(\boldsymbol k, t)]e^{-\nu k^2 h}, \\
+ * \hat{\boldsymbol w}_2(\boldsymbol k) &= \frac{3}{4}\hat{\boldsymbol u}( \boldsymbol k, t)e^{-\nu k^2 h/2}
* +
- * \frac{1}{4}(\hat{\bs w}_1(\bs k) + h \NL[\hat{\bs w}_1(\bs k)])e^{\nu k^2 h/2}, \\
- * \hat{\bs u}(\bs k, t+h) &= \frac{1}{3}\hat{\bs u}(\bs k, t)e^{-\nu k^2 h} +
- * \frac{2}{3}(\hat{\bs w}_2(\bs k) + h \NL[\hat{\bs w}_2(\bs k)])e^{-\nu k^2 h/2},
+ * \frac{1}{4}(\hat{\boldsymbol w}_1(\boldsymbol k) + h \textrm{NL}[\hat{\boldsymbol w}_1(\boldsymbol k)])e^{\nu k^2 h/2}, \\
+ * \hat{\boldsymbol u}(\boldsymbol k, t+h) &= \frac{1}{3}\hat{\boldsymbol u}(\boldsymbol k, t)e^{-\nu k^2 h} +
+ * \frac{2}{3}(\hat{\boldsymbol w}_2(\boldsymbol k) + h \textrm{NL}[\hat{\boldsymbol w}_2(\boldsymbol k)])e^{-\nu k^2 h/2},
* \f}
- *
- * .. [shu1988jcp] C.-W. Shu and S. Osher,
- * *Efficient implementation of essentially non-oscillatory shock-capturing schemes*.
- * J. Comput. Phys.,
- * **77**,
- * 439-471,
- * 1988
- * (doi 10.1016/0021-9991(88)90177-5)
*/
template <typename rnumber>
int NSE<rnumber>::ShuOsher(void)
diff --git a/documentation/chapters/cpp_doxygen.rst b/documentation/chapters/cpp_doxygen.rst
index e1bc1d94..68235690 100644
--- a/documentation/chapters/cpp_doxygen.rst
+++ b/documentation/chapters/cpp_doxygen.rst
@@ -1,19 +1,23 @@
------------
-C++ classes
------------
-
+---
+C++
+---
kspace
------
+`Full doxygen documentation link. <../../doxygen_html/classkspace.html>`_
+
.. doxygenclass:: kspace
:project: TurTLE
:members:
+
field
-----
+`Full doxygen documentation link. <../../doxygen_html/classfield.html>`_
+
.. doxygenclass:: field
:project: TurTLE
:members:
@@ -22,6 +26,8 @@ field
code_base
---------
+`Full doxygen documentation link. <../../doxygen_html/classcode__base.html>`_
+
.. doxygenclass:: code_base
:project: TurTLE
:members:
@@ -30,37 +36,93 @@ code_base
direct_numerical_simulation
---------------------------
+`Full doxygen documentation link. <../../doxygen_html/classdirect__numerical__simulation.html>`_
+
.. doxygenclass:: direct_numerical_simulation
:project: TurTLE
:members:
-..
- NSE
- ----
-
- .. doxygenclass:: NSE
- :project: TurTLE
- :members:
-
-
- NSVE
- ----
-
- .. doxygenclass:: NSVE
- :project: TurTLE
- :members:
-
-
- particle_set
- ------------
-
- .. doxygenclass:: particle_set
- :project: TurTLE
- :path: ...
- :members: [...]
- :protected-members:
- :private-members:
- :undoc-members:
- :outline:
- :no-link:
+NSE
+----
+
+`Full doxygen documentation link. <../../doxygen_html/classNSE.html>`_
+
+.. doxygenclass:: NSE
+ :project: TurTLE
+ :members:
+
+
+NSVE
+----
+
+`Full doxygen documentation link. <../../doxygen_html/classNSVE.html>`_
+
+.. doxygenclass:: NSVE
+ :project: TurTLE
+ :members:
+
+
+abstract_particle_set
+---------------------
+
+`Full doxygen documentation link. <../../doxygen_html/classabstract__particle__set.html>`_
+
+ .. doxygenclass:: abstract_particle_set
+ :project: TurTLE
+ :path: ...
+ :members: [...]
+ :protected-members:
+ :private-members:
+ :undoc-members:
+ :outline:
+ :no-link:
+
+
+abstract_particle_rhs
+---------------------
+
+`Full doxygen documentation link. <../../doxygen_html/classabstract__particle__rhs.html>`_
+
+ .. doxygenclass:: abstract_particle_rhs
+ :project: TurTLE
+ :path: ...
+ :members: [...]
+ :protected-members:
+ :private-members:
+ :undoc-members:
+ :outline:
+ :no-link:
+
+
+field_tinterpolator
+-------------------
+
+`Full doxygen documentation link. <../../doxygen_html/classfield__tinterpolator.html>`_
+
+ .. doxygenclass:: field_tinterpolator
+ :project: TurTLE
+ :path: ...
+ :members: [...]
+ :protected-members:
+ :private-members:
+ :undoc-members:
+ :outline:
+ :no-link:
+
+
+particle_solver
+---------------
+
+`Full doxygen documentation link. <../../doxygen_html/classparticle__solver.html>`_
+
+ .. doxygenclass:: particle_solver
+ :project: TurTLE
+ :path: ...
+ :members: [...]
+ :protected-members:
+ :private-members:
+ :undoc-members:
+ :outline:
+ :no-link:
+
diff --git a/documentation/sphinx_static/bibliography.rst b/documentation/sphinx_static/bibliography.rst
index a2c70575..c648c9ac 100644
--- a/documentation/sphinx_static/bibliography.rst
+++ b/documentation/sphinx_static/bibliography.rst
@@ -32,3 +32,8 @@ Bibliography
.. [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>`_
+
+.. [shu1988jcp] C.-W. Shu and S. Osher,
+ *Efficient implementation of essentially non-oscillatory shock-capturing schemes*.
+ `J. Comput. Phys. 77, 439-471 (1988) <http://dx.doi.org/10.1016/0021-9991(88)90177-5>`_
+
--
GitLab
From 5822991d960518f41fe54151d85338cd3397e0c5 Mon Sep 17 00:00:00 2001
From: Cristian C Lalescu <Cristian.Lalescu@mpcdf.mpg.de>
Date: Wed, 2 Feb 2022 13:34:46 +0100
Subject: [PATCH 12/24] adds logo to documentation
---
documentation/TurTLE_logo.svg | 165 ++++++++++++++++++++++++++++++++++
documentation/index.html.in | 12 ++-
meta/logo.py | 1 +
3 files changed, 175 insertions(+), 3 deletions(-)
create mode 100644 documentation/TurTLE_logo.svg
diff --git a/documentation/TurTLE_logo.svg b/documentation/TurTLE_logo.svg
new file mode 100644
index 00000000..420b8b6f
--- /dev/null
+++ b/documentation/TurTLE_logo.svg
@@ -0,0 +1,165 @@
+<?xml version="1.0" encoding="utf-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Created with matplotlib (https://matplotlib.org/) -->
+<svg height="162pt" version="1.1" viewBox="0 0 288 162" width="288pt" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <metadata>
+ <rdf:RDF xmlns:cc="http://creativecommons.org/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
+ <cc:Work>
+ <dc:type rdf:resource="http://purl.org/dc/dcmitype/StillImage"/>
+ <dc:date>2022-02-02T13:16:27.242777</dc:date>
+ <dc:format>image/svg+xml</dc:format>
+ <dc:creator>
+ <cc:Agent>
+ <dc:title>Matplotlib v3.3.4, https://matplotlib.org/</dc:title>
+ </cc:Agent>
+ </dc:creator>
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <defs>
+ <style type="text/css">*{stroke-linecap:butt;stroke-linejoin:round;}</style>
+ </defs>
+ <g id="figure_1">
+ <g id="patch_1">
+ <path d="M 0 162
+L 288 162
+L 288 0
+L 0 0
+z
+" style="fill:#ffffff;"/>
+ </g>
+ <g id="axes_1">
+ <g id="patch_2">
+ <path clip-path="url(#pa9854da833)" d="M 78.101695 63.915254
+C 68.338983 63.915254 29.288136 146.898305 53.694915 146.898305
+C 87.864407 146.898305 87.864407 63.915254 78.101695 63.915254
+z
+" style="fill:#007d7a;stroke:#007d7a;stroke-linejoin:miter;"/>
+ </g>
+ <g id="patch_3">
+ <path clip-path="url(#pa9854da833)" d="M 4.881356 112.728814
+C 29.288136 106.627119 29.288136 10.220339 109.586441 10.220339
+C 119.53258 10.158945 119.53258 10.158945 124.53597 15.040301
+C 129.53936 19.921657 129.53936 19.921657 129.6 29.745763
+C 129.53936 39.569868 129.53936 39.569868 124.53597 44.451224
+C 119.53258 49.33258 119.53258 49.33258 109.586441 49.271186
+C 29.288136 49.271186 53.694915 112.728814 4.881356 112.728814
+z
+" style="fill:#007d7a;stroke:#007d7a;stroke-linejoin:miter;"/>
+ </g>
+ <g id="patch_4">
+ <path clip-path="url(#pa9854da833)" d="M 175.728814 63.915254
+C 185.491525 63.915254 224.542373 146.898305 200.135593 146.898305
+C 165.966102 146.898305 165.966102 63.915254 175.728814 63.915254
+z
+" style="fill:#007d7a;stroke:#007d7a;stroke-linejoin:miter;"/>
+ </g>
+ <g id="patch_5">
+ <path clip-path="url(#pa9854da833)" d="M 152.054237 10.220339
+C 142.291525 10.220339 142.291525 10.220339 137.410169 15.101695
+C 132.528814 19.983051 132.528814 19.983051 132.528814 29.745763
+C 132.528814 39.508475 132.528814 39.508475 137.410169 44.389831
+C 142.291525 49.271186 142.291525 49.271186 152.054237 49.271186
+C 170.847458 49.271186 178.169492 59.033898 189.152542 59.033898
+C 190.372881 59.033898 192.813559 59.033898 197.694915 54.152542
+C 202.576271 49.271186 202.576271 49.271186 202.576271 44.389831
+C 202.576271 39.508475 202.576271 39.508475 197.694915 34.627119
+C 195.254237 32.186441 175.728814 10.220339 147.172881 10.220339
+z
+" style="fill:#007d7a;stroke:#007d7a;stroke-linejoin:miter;"/>
+ </g>
+ <g id="patch_6">
+ <path clip-path="url(#pa9854da833)" d="M 200.135593 56.59322
+C 203.79661 52.932203 203.79661 52.932203 207.457627 52.932203
+C 211.118644 52.932203 211.118644 52.932203 214.779661 56.59322
+C 214.779661 56.59322 231.864407 76.118644 231.864407 100.525424
+L 246.508475 100.525424
+C 247.484746 102.966102 253.830508 111.752542 261.152542 112.728814
+L 219.661017 112.728814
+C 219.661017 100.525424 214.779661 76.118644 200.135593 66.355932
+C 197.694915 63.915254 197.694915 63.915254 197.694915 61.474576
+C 197.694915 59.033898 197.694915 59.033898 200.135593 56.59322
+z
+" style="fill:#007d7a;stroke:#007d7a;stroke-linejoin:miter;"/>
+ </g>
+ <g id="patch_7">
+ <path clip-path="url(#pa9854da833)" d="M 248.949153 93.20339
+C 248.949153 19.983051 283.118644 49.271186 283.118644 76.118644
+C 258.711864 54.152542 253.830508 83.440678 278.237288 83.440678
+C 258.711864 83.440678 253.830508 102.966102 283.118644 93.20339
+C 283.118644 122.491525 248.949153 112.728814 248.949153 93.20339
+z
+" style="fill:#007d7a;stroke:#007d7a;stroke-linejoin:miter;"/>
+ </g>
+ <g id="text_1">
+ <!-- ur -->
+ <g style="fill:#007d7a;" transform="translate(90.487754 112.728814)scale(0.72 -0.72)">
+ <defs>
+ <path d="M 37.203125 6.40625
+L 37.40625 6.40625
+L 37.90625 0
+C 37.90625 -0.203125 38.203125 -0.296875 38.796875 -0.296875
+C 40.09375 -0.203125 43.09375 0 44.5 0
+C 45.796875 0 50.59375 -0.09375 51.90625 -0.296875
+L 52.09375 0
+C 51.296875 4.296875 50.40625 11.703125 50.40625 19.203125
+L 50.40625 24.90625
+C 50.40625 32.40625 50.40625 37.59375 51.296875 42.90625
+L 51.203125 43.203125
+C 51.203125 43.203125 47 42.90625 43.5 42.90625
+C 40.09375 42.90625 36.703125 43.203125 36.703125 43.203125
+L 36.5 42.90625
+C 37.203125 37.296875 37.203125 32.5 37.203125 24.90625
+L 37.203125 16.90625
+C 37.203125 11.09375 30.40625 6.703125 26 6.703125
+C 23 6.703125 20.09375 7.703125 20.296875 15.90625
+L 20.5 24.90625
+C 20.59375 32.40625 20.796875 37.703125 21.296875 42.90625
+L 21.203125 43.203125
+C 21.203125 43.203125 17.203125 42.90625 13.703125 42.90625
+C 10.296875 42.90625 6.703125 43.203125 6.703125 43.203125
+L 6.5 42.90625
+C 7.09375 37.203125 7.40625 32.09375 7.296875 24.90625
+L 7.09375 12.59375
+C 7 5.703125 10.5 -1 20.40625 -1
+C 24.5 -1 31.59375 0.40625 37.203125 6.40625
+z
+" id="LinBiolinumOB-117"/>
+ <path d="M 22.5 34.90625
+L 22 35.203125
+C 22 37.40625 21.90625 41.59375 21.796875 42.5
+C 21.59375 43.09375 21.5 43.5 20.90625 43.5
+C 18 43 11.5 43 8 43.203125
+L 7.796875 42.90625
+C 8.5 38.59375 8.90625 30.90625 8.90625 23.5
+L 8.90625 18
+C 8.90625 10.5 8.703125 5.40625 7.90625 0
+L 8 -0.296875
+C 8 -0.296875 11.203125 0 14.703125 0
+C 18.09375 0 22.90625 -0.296875 22.90625 -0.296875
+L 23.09375 0
+C 22.296875 5.703125 22.09375 10.40625 22.09375 18
+L 22.09375 25.296875
+C 22.09375 33 28.90625 34.203125 30.5 34.203125
+C 32.40625 34.203125 34.5 33.703125 36.296875 32.296875
+L 38.09375 32.5
+L 40.09375 42.796875
+L 39.703125 43.203125
+C 38 43.703125 36.40625 43.90625 34.59375 43.90625
+C 29.90625 43.90625 25.09375 38.796875 22.5 34.90625
+z
+" id="LinBiolinumOB-114"/>
+ </defs>
+ <use xlink:href="#LinBiolinumOB-117"/>
+ <use x="59.099991" xlink:href="#LinBiolinumOB-114"/>
+ </g>
+ </g>
+ </g>
+ </g>
+ <defs>
+ <clipPath id="pa9854da833">
+ <rect height="161.084746" width="288" x="0" y="0.457627"/>
+ </clipPath>
+ </defs>
+</svg>
diff --git a/documentation/index.html.in b/documentation/index.html.in
index fa9500bc..86140305 100644
--- a/documentation/index.html.in
+++ b/documentation/index.html.in
@@ -1,9 +1,14 @@
<html>
<title>TurTLE v@TURTLE_VERSION@</title>
+ <body>
<h1>TurTLE v@TURTLE_VERSION@</h1>
- <p>
- Thank you for browsing the documentation of <a href="https://gitlab.mpcdf.mpg.de/TurTLE/turtle">TurTLE</a>.
- </p>
+ <figure>
+ <a href="https://gitlab.mpcdf.mpg.de/TurTLE/turtle">
+ <img
+ src="TurTLE_logo.svg"
+ alt="TurTLE"></a>
+ <figcaption>Thank you for your interest in TurTLE.</figcaption>
+ </figure>
<p>
TurTLE stands for "Turbulence Tools: Lagrangian and Eulerian" and it is
developed and maintained by the Wilczek group at the
@@ -32,6 +37,7 @@
This contains tutorials, the Python library documentation, and part of the C++ Doxygen output.
</li>
</ul>
+ </body>
<footer>
Last updated @BUILD_DATE@.
</footer>
diff --git a/meta/logo.py b/meta/logo.py
index 85d53d55..e3d9da54 100644
--- a/meta/logo.py
+++ b/meta/logo.py
@@ -390,6 +390,7 @@ def drawn_full():
a.set_xlim(-2.6, 3.3)
a.set_ylim(-1., 2.3)
f.savefig('TurTLE_logo.pdf')
+ f.savefig('TurTLE_logo.svg')
return None
def drawn():
--
GitLab
From 56e061c18cd40fd63f6c8f933875d50010e4bd0d Mon Sep 17 00:00:00 2001
From: Cristian C Lalescu <Cristian.Lalescu@mpcdf.mpg.de>
Date: Wed, 2 Feb 2022 14:42:30 +0100
Subject: [PATCH 13/24] fixes logo copy
---
documentation/merge_doc_html.sh.in | 3 +++
1 file changed, 3 insertions(+)
diff --git a/documentation/merge_doc_html.sh.in b/documentation/merge_doc_html.sh.in
index 8958a3e8..0844d2e7 100644
--- a/documentation/merge_doc_html.sh.in
+++ b/documentation/merge_doc_html.sh.in
@@ -7,6 +7,9 @@ rsync --archive \
rsync --archive \
@CMAKE_CURRENT_BINARY_DIR@/sphinx_html \
@CMAKE_CURRENT_BINARY_DIR@/public/
+rsync --archive \
+ @PROJECT_SOURCE_DIR@/documentation/TurTLE_logo.svg \
+ @CMAKE_CURRENT_BINARY_DIR@/public/
cp \
@CMAKE_CURRENT_BINARY_DIR@/doc_full_index.html \
@CMAKE_CURRENT_BINARY_DIR@/public/index.html
--
GitLab
From 538cf08501a66c41972b569e607e0683c1e9d994 Mon Sep 17 00:00:00 2001
From: Cristian C Lalescu <Cristian.Lalescu@mpcdf.mpg.de>
Date: Wed, 2 Feb 2022 15:47:27 +0100
Subject: [PATCH 14/24] fixes gitlab ci logo
---
.gitlab-ci.yml | 1 +
1 file changed, 1 insertion(+)
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 975afa0f..0e6a9499 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -199,6 +199,7 @@ pages:
- mv build-doc/sphinx_html public/sphinx_html
#- mv TurTLE_manual.pdf public/
- mv build-doc/doc_full_index.html public/index.html
+ - mv build-doc/TurTLE_logo.svg public/
artifacts:
paths:
- public
--
GitLab
From e70db9a45cf66735672089386a0da5baaf3ab2c3 Mon Sep 17 00:00:00 2001
From: Cristian C Lalescu <Cristian.Lalescu@mpcdf.mpg.de>
Date: Wed, 2 Feb 2022 15:53:20 +0100
Subject: [PATCH 15/24] fixes logo source folder
---
.gitlab-ci.yml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 0e6a9499..9dae34e5 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -199,7 +199,7 @@ pages:
- mv build-doc/sphinx_html public/sphinx_html
#- mv TurTLE_manual.pdf public/
- mv build-doc/doc_full_index.html public/index.html
- - mv build-doc/TurTLE_logo.svg public/
+ - cp documentation/TurTLE_logo.svg public/
artifacts:
paths:
- public
--
GitLab
From 5f141382af5a4a996017910e71de593e5b065a64 Mon Sep 17 00:00:00 2001
From: Cristian C Lalescu <Cristian.Lalescu@mpcdf.mpg.de>
Date: Thu, 3 Feb 2022 08:51:42 +0100
Subject: [PATCH 16/24] fixes link, updates paragraph on "external projects"
---
README.rst | 24 +++++++++++++++++-------
1 file changed, 17 insertions(+), 7 deletions(-)
diff --git a/README.rst b/README.rst
index e0c80980..fbbc1818 100644
--- a/README.rst
+++ b/README.rst
@@ -257,13 +257,20 @@ equal to :code:`<TURTLE_DIR>`.
make install
Congratulations, you have installed TurTLE! Feel free to checkout the
-`tutorial <http://turtle.pages.mpcdf.de/turtle/sphinx_html/chapters/tutorial.html>`_.
+`overview <http://turtle.pages.mpcdf.de/turtle/sphinx_html/sphinx_static/overview.html>`_.
-**Using TurTLE from an external project**.
+**Using TurTLE as a library**.
-TurTLE creates and installs 3 files alongside the C++ headers and
-library:
+When requiring functionality not provided by TurTLE, we recommend that
+users use TurTLE as a library from "external projects".
+We are yet to write an explicit tutorial of the procedure, but TurTLE
+already contains examples of the approach:
+* `TurTLE/test/test_Heun_p2p.py` and related C++ files
+* `TurTLE/test/test_particle_deleter.py` and related C++ files
+
+In order for the procedure to work, please note the 3 files that TurTLE installs
+alongside the C++ headers and library:
.. code:: bash
@@ -271,9 +278,12 @@ library:
TurTLE_EXPORT.cmake
TurTLE_EXPORT-noconfig.cmake
-These files are installed under `${TURTLE_DIR}/lib`.
-In case these files provide incomplete information, it is necessary to update
-the cmake input config file: `turtle/cmake/TurTLEConfig.cmake.in`.
+These files are installed under `${TURTLE_DIR}/lib`, and they are
+required for such external projects to work.
+In case you encounter compilation errors even though TurTLE itself works
+without problems, it is probably necessary to update
+the cmake input config file: `turtle/cmake/TurTLEConfig.cmake.in` ---
+you are welcome to contact us with the details.
**Uninstall**
--
GitLab
From 89f763b5f31c44eb1d47558a7eaae036a452aec1 Mon Sep 17 00:00:00 2001
From: Lukas Bentkamp <lukas.bentkamp@uni-bayreuth.de>
Date: Fri, 4 Feb 2022 13:23:55 +0100
Subject: [PATCH 17/24] Fix: path to cmake
---
README.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/README.rst b/README.rst
index fbbc1818..3299e012 100644
--- a/README.rst
+++ b/README.rst
@@ -190,8 +190,8 @@ equal to :code:`<TURTLE_DIR>`.
make
make install
- The directory `<CMAKE_DIR>` is only relevant to later executing
- the `cmake` binary (which can be found under :code:`<CMAKE_DIR>/bin` after
+ The directory :code:`<CMAKE_DIR>` is only relevant to later executing
+ the :code:`cmake` binary (which can be found under :code:`<CMAKE_DIR>/bin` after
installation).
--
GitLab
From 4a1ef066e7a4475c9381a5f62beb2a30f2a5569e Mon Sep 17 00:00:00 2001
From: Lukas Bentkamp <lukas.bentkamp@uni-bayreuth.de>
Date: Fri, 4 Feb 2022 14:09:54 +0100
Subject: [PATCH 18/24] fix: bullet list and turtle_dir
---
README.rst | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/README.rst b/README.rst
index 3299e012..1f2ef7e2 100644
--- a/README.rst
+++ b/README.rst
@@ -266,6 +266,7 @@ When requiring functionality not provided by TurTLE, we recommend that
users use TurTLE as a library from "external projects".
We are yet to write an explicit tutorial of the procedure, but TurTLE
already contains examples of the approach:
+
* `TurTLE/test/test_Heun_p2p.py` and related C++ files
* `TurTLE/test/test_particle_deleter.py` and related C++ files
@@ -278,7 +279,7 @@ alongside the C++ headers and library:
TurTLE_EXPORT.cmake
TurTLE_EXPORT-noconfig.cmake
-These files are installed under `${TURTLE_DIR}/lib`, and they are
+These files are installed under :code:`<TURTLE_DIR>/lib`, and they are
required for such external projects to work.
In case you encounter compilation errors even though TurTLE itself works
without problems, it is probably necessary to update
--
GitLab
From 5f014977a2dc038a5c0361d27fef53fd22f92027 Mon Sep 17 00:00:00 2001
From: Cristian C Lalescu <Cristian.Lalescu@mpcdf.mpg.de>
Date: Fri, 4 Feb 2022 16:41:53 +0100
Subject: [PATCH 19/24] clarifies relevance of .cmake files
---
README.rst | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/README.rst b/README.rst
index 1f2ef7e2..832a27d9 100644
--- a/README.rst
+++ b/README.rst
@@ -280,7 +280,8 @@ alongside the C++ headers and library:
TurTLE_EXPORT-noconfig.cmake
These files are installed under :code:`<TURTLE_DIR>/lib`, and they are
-required for such external projects to work.
+required for such external projects to work (the Python wrapper calls
+`cmake` behind the scenes, and `cmake` will need these files).
In case you encounter compilation errors even though TurTLE itself works
without problems, it is probably necessary to update
the cmake input config file: `turtle/cmake/TurTLEConfig.cmake.in` ---
--
GitLab
From a04a5c27c7ff4e984ca6e2572852008537df4218 Mon Sep 17 00:00:00 2001
From: Cristian C Lalescu <Cristian.Lalescu@mpcdf.mpg.de>
Date: Fri, 4 Feb 2022 16:42:18 +0100
Subject: [PATCH 20/24] adds example CC and CXX values
---
bash_setup_template.sh | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/bash_setup_template.sh b/bash_setup_template.sh
index 3f19fb62..118d3338 100644
--- a/bash_setup_template.sh
+++ b/bash_setup_template.sh
@@ -3,8 +3,8 @@
# Load dependencies here if necessary, e.g. `module load cmake`
# module-dependent variables
-export CC=<CC> # Preferred C compiler
-export CXX=<CXX> # Preferred C++ compiler
+export CC=<CC> # Preferred C compiler, e.g. `gcc`
+export CXX=<CXX> # Preferred C++ compiler, e.g. `g++`
export MPI_HOME=<MPI_HOME> # MPI installation directory
export FFTW_ROOT=<FFTW_DIR> # Base directory of FFTW
export FFTW_DIR=<FFTW_DIR> # Base directory of FFTW
@@ -54,4 +54,4 @@ export PATH=${CUSTOM_INSTALL_PATH}/bin:${PATH}
export CMAKE_PREFIX_PATH=${CUSTOM_INSTALL_PATH}/lib
# activate python virtual environment
-source ${TURTLE_ROOT}/bin/activate
\ No newline at end of file
+source ${TURTLE_ROOT}/bin/activate
--
GitLab
From 18b21424c65b42c301626aad880b16f38f152a1c Mon Sep 17 00:00:00 2001
From: Cristian C Lalescu <Cristian.Lalescu@mpcdf.mpg.de>
Date: Fri, 4 Feb 2022 16:44:31 +0100
Subject: [PATCH 21/24] removes outdated comment
---
bash_setup_template.sh | 10 ++++++----
1 file changed, 6 insertions(+), 4 deletions(-)
diff --git a/bash_setup_template.sh b/bash_setup_template.sh
index 118d3338..e00c0e27 100644
--- a/bash_setup_template.sh
+++ b/bash_setup_template.sh
@@ -10,6 +10,7 @@ export FFTW_ROOT=<FFTW_DIR> # Base directory of FFTW
export FFTW_DIR=<FFTW_DIR> # Base directory of FFTW
export HDF5_ROOT=<HDF5_DIR> # Base directory of HDF5
+########################################################################
# OPTIONAL
#
# export PINCHECK_ROOT=<PINCHECK_ROOT>
@@ -18,7 +19,9 @@ export HDF5_ROOT=<HDF5_DIR> # Base directory of HDF5
# MPI processes and OpenMP threads are pinned properly to hardware threads.
# It is available from https://gitlab.mpcdf.mpg.de/khr/pincheck.
# The pincheck headers need to be placed under `<PINCHECK_ROOT>/include`.
+########################################################################
+########################################################################
# OPTIONAL
#
# export TURTLE_COMPILATION_FLAGS=<COMPILATION_FLAGS>
@@ -27,7 +30,9 @@ export HDF5_ROOT=<HDF5_DIR> # Base directory of HDF5
# For clusters of unknown architecture it helps to log into
# individual nodes and run the following command:
# gcc -march=native -Q --help=target
+########################################################################
+########################################################################
# OPTIONAL
#
# export FFTW_INCDIR=<FFTW_INCDIR> # Directory containing FFTW header files
@@ -39,10 +44,7 @@ export HDF5_ROOT=<HDF5_DIR> # Base directory of HDF5
# FFTW libraries (serial, MPI and OpenMP) were located in different
# folders, hence the options of specifying the details.
# See also lines 264 through 282 of `CMakeLists.txt`.
-#
-# If using openmpi you may need to recompile openmpi with the
-# `--enable-mpi1-compatibility` flag, in order for HDF5 to compile and
-# link.
+########################################################################
# Turtle installation directory
export TURTLE_ROOT=<TURTLE_DIR>
--
GitLab
From ac60fb7a8ad72b1024567bc22d65c7e0ebe8e4aa Mon Sep 17 00:00:00 2001
From: Cristian C Lalescu <Cristian.Lalescu@mpcdf.mpg.de>
Date: Fri, 4 Feb 2022 16:46:18 +0100
Subject: [PATCH 22/24] adds example for MPI_HOME
---
bash_setup_template.sh | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/bash_setup_template.sh b/bash_setup_template.sh
index e00c0e27..863d3ee3 100644
--- a/bash_setup_template.sh
+++ b/bash_setup_template.sh
@@ -5,7 +5,7 @@
# module-dependent variables
export CC=<CC> # Preferred C compiler, e.g. `gcc`
export CXX=<CXX> # Preferred C++ compiler, e.g. `g++`
-export MPI_HOME=<MPI_HOME> # MPI installation directory
+export MPI_HOME=<MPI_HOME> # MPI installation directory, e.g. ${I_MPI_ROOT}
export FFTW_ROOT=<FFTW_DIR> # Base directory of FFTW
export FFTW_DIR=<FFTW_DIR> # Base directory of FFTW
export HDF5_ROOT=<HDF5_DIR> # Base directory of HDF5
--
GitLab
From 0a60277dc17d2f625fdd92669eeebad5d9b91650 Mon Sep 17 00:00:00 2001
From: Lukas Bentkamp <lukas.bentkamp@uni-bayreuth.de>
Date: Mon, 7 Feb 2022 09:21:02 +0000
Subject: [PATCH 23/24] Update bandpass.rst numbering
---
documentation/sphinx_static/bandpass.rst | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/documentation/sphinx_static/bandpass.rst b/documentation/sphinx_static/bandpass.rst
index 7c892160..e4285ab7 100644
--- a/documentation/sphinx_static/bandpass.rst
+++ b/documentation/sphinx_static/bandpass.rst
@@ -25,14 +25,14 @@ and they are roughly the procedure followed when writing the
3. Write down the explicit numerical task.
Identify algorithms, parameters, check whether required functionality
is available.
-5. Write down simple outline of new code to implement within
+4. Write down simple outline of new code to implement within
``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`
+5. Create a new :code:``git`` branch to work on, :code:`feature/<mypptool>`.
+6. 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
+7. 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
the required functionality is implemented.
--
GitLab
From 039bb49ce2999f164bdc0bcb1fd4f4a9e0735d2a Mon Sep 17 00:00:00 2001
From: Lukas Bentkamp <lukas.bentkamp@uni-bayreuth.de>
Date: Mon, 7 Feb 2022 09:22:20 +0000
Subject: [PATCH 24/24] Fix quotes
---
documentation/sphinx_static/bandpass.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/documentation/sphinx_static/bandpass.rst b/documentation/sphinx_static/bandpass.rst
index e4285ab7..8a3c12f0 100644
--- a/documentation/sphinx_static/bandpass.rst
+++ b/documentation/sphinx_static/bandpass.rst
@@ -27,7 +27,7 @@ and they are roughly the procedure followed when writing the
is available.
4. Write down simple outline of new code to implement within
``initialize``, ``work_on_current_iteration`` and ``finalize``.
-5. Create a new :code:``git`` branch to work on, :code:`feature/<mypptool>`.
+5. Create a new :code:`git` branch to work on, :code:`feature/<mypptool>`.
6. 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`
--
GitLab