diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 10776184bcdbded0ca7496d9d76663374633efda..9dae34e5e18ae4d9fb7106aea800412b0ca7bc5f 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -153,13 +153,12 @@ 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 - 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,14 +195,16 @@ 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/index.html + - cp documentation/TurTLE_logo.svg public/ artifacts: paths: - public - only: - - tags +# only: +# - tags tags: - docker needs: diff --git a/CMakeLists.txt b/CMakeLists.txt index 627474c66f465e29bec62d833e44f9bda35c1a72..b983626e1f70765f302f9246f9cfd5d9d46fc5fd 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/README.rst b/README.rst index bf605a97157e3992fa865c0ef0a25d22d2352c6e..832a27d96a8a525f6df52c8319ce930bee0b2616 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 ------- @@ -54,7 +52,7 @@ Computing and Data Facility. TurTLE contains contributions from: - .. include:: AUTHORS +.. include:: AUTHORS .. _sec-installation: @@ -96,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: @@ -119,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 @@ -140,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 @@ -171,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 @@ -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). @@ -204,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 @@ -253,13 +257,21 @@ 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 as a 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: -**Using TurTLE from an external project**. +* `TurTLE/test/test_Heun_p2p.py` and related C++ files +* `TurTLE/test/test_particle_deleter.py` and related C++ files -TurTLE creates and installs 3 files alongside the C++ headers and -library: +In order for the procedure to work, please note the 3 files that TurTLE installs +alongside the C++ headers and library: .. code:: bash @@ -267,9 +279,13 @@ 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 :code:`<TURTLE_DIR>/lib`, and they are +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` --- +you are welcome to contact us with the details. **Uninstall** @@ -342,7 +358,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 diff --git a/bash_setup_template.sh b/bash_setup_template.sh index 3f19fb6203c1a95fff6a1656bf70368c8ede8aa8..863d3ee3aa9e19b468079dacb24d47e5c7115001 100644 --- a/bash_setup_template.sh +++ b/bash_setup_template.sh @@ -3,13 +3,14 @@ # 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 MPI_HOME=<MPI_HOME> # MPI installation directory +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, 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 +######################################################################## # 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> @@ -54,4 +56,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 diff --git a/configure_python.sh b/configure_python.sh index 4356bef4008e836acaee8d9ca66a366350e7a66a..bc38e9eef17722eec5ea71fd86838ccd7ced2404 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 diff --git a/cpp/full_code/NSE.cpp b/cpp/full_code/NSE.cpp index fac9a0b3c622d46bdbddd5e91fd9c7f40bed0140..2e1c0b68e0b36b328692a6c2155bc17a840c5929 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/cpp/kspace.cpp b/cpp/kspace.cpp index 369db6236fb8eaad52c9e0c2a7fdca35fb5d5198..b1f40ae446e469888ae645d0dd751aae4635817d 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/TurTLE_logo.svg b/documentation/TurTLE_logo.svg new file mode 100644 index 0000000000000000000000000000000000000000..420b8b6f9477151c5c281a49534bc252c82519a1 --- /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/chapters/bandpass.rst b/documentation/chapters/bandpass.rst deleted file mode 100644 index 400dffe56253418aa586782ab6a783f6e407ba4a..0000000000000000000000000000000000000000 --- 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/chapters/cpp_doxygen.rst b/documentation/chapters/cpp_doxygen.rst index e1bc1d942c3f2fa5ed1bac65d66bc245326973d6..6823569063ce9e7b58976d412d280e2f3eacd807 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/conf.py.in b/documentation/conf.py.in index c05020c9fd0b05b1186b1c4facbbe5b22b7f4522..89e40fedc21df0f888c8ac31c19f653007db471b 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 0000000000000000000000000000000000000000..8614030531341f1e033c295771b5e1ccbc7793d7 --- /dev/null +++ b/documentation/index.html.in @@ -0,0 +1,44 @@ +<html> + <title>TurTLE v@TURTLE_VERSION@</title> + <body> + <h1>TurTLE v@TURTLE_VERSION@</h1> + <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 + <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> + </body> + <footer> + Last updated @BUILD_DATE@. + </footer> +</html> diff --git a/documentation/index.rst b/documentation/index.rst index 7788a2f226901d8a66b728ff6aa45dda63e8ff33..36c60cd39a51e02fe717312b31da22ef1107032a 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/merge_doc_html.sh.in b/documentation/merge_doc_html.sh.in new file mode 100644 index 0000000000000000000000000000000000000000..0844d2e7ede25cb140159e132579315300beae93 --- /dev/null +++ b/documentation/merge_doc_html.sh.in @@ -0,0 +1,15 @@ +#! /usr/bin/env bash + +mkdir -p public/doxygen_html +rsync --archive \ + @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/ +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 diff --git a/documentation/sphinx_static/bandpass.rst b/documentation/sphinx_static/bandpass.rst new file mode 100644 index 0000000000000000000000000000000000000000..8a3c12f06c7f358e9c72243ae93ae65782287612 --- /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. +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>`. +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. +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. + diff --git a/documentation/sphinx_static/bibliography.rst b/documentation/sphinx_static/bibliography.rst index 1b90b08284d75040e5732b0d84351946eb983036..c648c9ac4e4da6bfc8dafba4d4ab24ff312745c1 100644 --- a/documentation/sphinx_static/bibliography.rst +++ b/documentation/sphinx_static/bibliography.rst @@ -19,3 +19,21 @@ 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>`_ + +.. [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>`_ + 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 5f18cf1f4dd40042cd6154b6df994fdea9d6981a..7dc9836b820d1067bbf42d4fd3f7f6fc94530a45 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 0000000000000000000000000000000000000000..3978ebb7c9951c1b136a09f865af8f54e70a0e68 --- /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 81% rename from documentation/chapters/tutorial.rst rename to documentation/sphinx_static/overview.rst index 4ee154cc6544a7929546a830984f6ca05f2c667e..2c640529f078bb56646e220cec24a7098991a078 100644 --- a/documentation/chapters/tutorial.rst +++ b/documentation/sphinx_static/overview.rst @@ -1,6 +1,6 @@ -===================== -Overview and Tutorial -===================== +======== +Overview +======== ---------------- General comments @@ -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/meta/logo.py b/meta/logo.py index 85d53d55b6a9108d985425eb69805c1cbeebc0c8..e3d9da5494e5a73b7848d378846be58b7079ca4c 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():