README.rst 13.3 KB
Newer Older
Lambert Theisen's avatar
Lambert Theisen committed
1
.. image:: logo.png
Lambert Theisen's avatar
Lambert Theisen committed
2
    :width: 200px
Lambert Theisen's avatar
Lambert Theisen committed
3
    :alt: logo
Lambert Theisen's avatar
Lambert Theisen committed
4
5
6

.. inclusion-marker

Lambert Theisen's avatar
Lambert Theisen committed
7
fenicsR13
8
================================================================================
Lambert Theisen's avatar
Lambert Theisen committed
9

10
|pipeline| |coverage| |version| |website|
Lambert Theisen's avatar
Lambert Theisen committed
11
12
13
14
15
16

``#extendedGasDynamics`` ``#using`` ``#FEniCS``

  Repository for Master thesis project regarding FEM simulations for
  non-equilibrium gas dynamics.

17
Installation
18
--------------------------------------------------------------------------------
Lambert Theisen's avatar
Lambert Theisen committed
19
20
21
22

It is recommended to use the program within a Docker container.

Docker
23
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Lambert Theisen's avatar
Lambert Theisen committed
24

25
First install `Docker Desktop`_ for your OS. Then:
Lambert Theisen's avatar
Lambert Theisen committed
26
27
28

.. _`Docker Desktop`: https://www.docker.com/products/docker-desktop

Lambert Theisen's avatar
Lambert Theisen committed
29
.. code-block:: bash
Lambert Theisen's avatar
Lambert Theisen committed
30

Lambert Theisen's avatar
Lambert Theisen committed
31
32
33
34
35
    # Clone Repository and open main folder
    git clone git@git.rwth-aachen.de:lamBOO/fenicsR13.git
    cd fenicsR13

    # Build and run fenics service
Lambert Theisen's avatar
Lambert Theisen committed
36
37
    docker-compose build fenics
    docker-compose run fenics
38

39
40
    ### 1.START) Execute lid_driven_cavity example
    # Move to folder:
41
    cd examples/lid_driven_cavity
42
    # Create mesh:
43
    python3 create_meshes.py
44
    # Run program with given input file:
45
    python3 ../../src/fenicsR13.py input.yml
46
47
    # Go to folder with simulation results (=casename in input.yml)
    cd lid_driven_cavity
Lambert Theisen's avatar
Lambert Theisen committed
48
49
    # Perform GUI visualization on XDMF-files with Paraview:
    echo "Data files:" $(find . -name "*.xdmf")
50
    echo "E.g.: Open Paraview > File > Open > u_0.xdmf > Apply filters"
Lambert Theisen's avatar
Lambert Theisen committed
51
52
    # Inspect PDF field plots:
    echo "Field plots:" $(find . -name "*.pdf")
53
    # Leave directory:
54
    cd ../..
55
    ### 1.END)
56

57
58
    ### 2.START) Execute channel_flow example
    # Move to folder:
59
    cd examples/channel_flow
60
    # Create mesh:
61
    python3 create_meshes.py
62
    # Run program with given input file:
63
    python3 ../../src/fenicsR13.py input.yml
64
65
    # Go to folder with simulation results (=casename in input.yml)
    cd channel_flow
Lambert Theisen's avatar
Lambert Theisen committed
66
67
    # Perform GUI visualization on XDMF-files with Paraview:
    echo "Data files:" $(find . -name "*.xdmf")
68
    echo "E.g.: Open Paraview > File > Open > u_0.xdmf > Apply filters"
Lambert Theisen's avatar
Lambert Theisen committed
69
70
    # Inspect PDF field plots:
    echo "Field plots:" $(find . -name "*.pdf")
71
72
73
74
    # Generate correlation data between Knudsen number and massflow
    bash postprocessing.sh
    cat table.csv
    echo "Knudsen paradox ;-)"
75
    # Leave directory:
76
    cd ../..
77
    ### 2.END)
78

79
80
    ### 3.START) Execute convergence test
    # Move to folder:
81
    cd tests/r13
82
83
84
    # Meshes already in Git:
    ls ../mesh
    # Run program with given input file:
85
    python3 ../../src/fenicsR13.py inputs/r13_1_coeffs_nosources_norot_inflow_p1p1p1p1p1_stab.yml
86
87
88
89
90
91
    # Go to folder with simulation results (=casename in input.yml)
    cd r13_1_coeffs_nosources_norot_inflow_p1p1p1p1p1_stab
    # Open errors:
    cat errors.csv
    # Open PDF convergence plot:
    echo "E.g.: Open Adobe Reader > File > Open > convergence_plot_r13_1_coeffs_nosources_norot_inflow_p1p1p1p1p1_stab.pdf"
Lambert Theisen's avatar
Lambert Theisen committed
92
93
    # Perform GUI visualization on XDMF-files with Paraview:
    echo "Data files:" $(find . -name "*.xdmf")
94
95
96
97
    echo "E.g.: Open Paraview > File > Open > u_0.xdmf > Apply filters"
    # Leave directory:
    cd ../..
    ### 3.END)
98
99
100
101

    # Parallel execution ("-u" to flash stdout)
    # Usage: mpirun -n <numberOfProcesses> <serialCommand>
    # E.g.: mpirun -n 4 python3 -u ../../src/fenicsR13.py input.yml
Lambert Theisen's avatar
Lambert Theisen committed
102

Lambert Theisen's avatar
Lambert Theisen committed
103
The main folder of this repository contains a ``Dockerfile`` defining the used environment. Here, we used the optimized and official FEniCS Docker image and include ``Gmsh`` and install some requirements from the ``requirements.txt``. This can take a while, especially the ``Gmsh`` mirror can be quite slow. To avoid very long execution commands (``docker run <..> -v <volume share> <etc..>``), a ``docker-compose.yml`` is used to store all these parameters. ``docker-compose`` acts as an wrapper for the Docker execution.
Lambert Theisen's avatar
Lambert Theisen committed
104

105
106
107
108
109
110
111
The ``fenics`` environment (also called *service* in the ``docker-compose.yml``) first has to be build and can be executed afterwards. The steps to perform read

.. code-block:: bash

    # build and run fenics service
    docker-compose build fenics
    docker-compose run fenics
Lambert Theisen's avatar
Lambert Theisen committed
112

113
The whole repository is mounted as a volume under ``/home/fenics/shared`` in the container and should be the default folder on startup. To execute a simulation case, go to to the case folder (e.g. ``examples/lid_driven_cavity``) and execute the solver main program ``fenicsR13.py`` (which is located in the ``src``-directory in the top level) while specifying the input file as first command line argument. This can be for example ``python3 ../../src/fenicsR13.py inout.yml``. Output files should be written to a folder which is named after the ``output_folder`` keyword of the ``input.yml``. Each output field (temperature, pressure,...) has a ``.h5``-file and an ``.xdmf``-file. The XDMF-files can be opened in Paraview to perform visualization.
Lambert Theisen's avatar
Lambert Theisen committed
114

Lambert Theisen's avatar
Lambert Theisen committed
115
It is possible to use a Jupyter sever or a X11 forwarding but this is not recommended anymore. All relevant plots are now written by default without the need for the tricky X11 forwarding or interactive usage with Jupyter.
Lambert Theisen's avatar
Lambert Theisen committed
116

Lambert Theisen's avatar
Lambert Theisen committed
117
118
Documentation
--------------------------------------------------------------------------------
Lambert Theisen's avatar
Lambert Theisen committed
119

Lambert Theisen's avatar
Lambert Theisen committed
120
Documentation using Sphinx is available.
Lambert Theisen's avatar
Lambert Theisen committed
121

Lambert Theisen's avatar
Lambert Theisen committed
122
Pre-Build Version
123
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Lambert Theisen's avatar
Lambert Theisen committed
124

Lambert Theisen's avatar
Lambert Theisen committed
125
Visit the hosted version on `Gitlab Pages`_ or download the artifacts from Gitlab's CI ``pages``-pipeline.
126

Lambert Theisen's avatar
Lambert Theisen committed
127
.. _`Gitlab Pages`: https://lamboo.pages.rwth-aachen.de/fenicsR13/
Lambert Theisen's avatar
Lambert Theisen committed
128
129

Manual Generation
130
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Lambert Theisen's avatar
Lambert Theisen committed
131

Lambert Theisen's avatar
Lambert Theisen committed
132
.. code-block:: bash
Lambert Theisen's avatar
Lambert Theisen committed
133

Lambert Theisen's avatar
Lambert Theisen committed
134
    # cat .gitlab-ci.yml
135
    cd docs
Lambert Theisen's avatar
Lambert Theisen committed
136
137
138
139
140
    sphinx-apidoc -o source/src ../src
    sphinx-apidoc -o source/tests/heat ../tests/heat
    sphinx-apidoc -o source/tests/stress ../tests/stress
    sphinx-apidoc -o source/tests/r13 ../tests/r13
    sphinx-apidoc -o source/examples ../examples
141
    make html
Lambert Theisen's avatar
Lambert Theisen committed
142
    make latex
Lambert Theisen's avatar
Lambert Theisen committed
143

Lambert Theisen's avatar
Lambert Theisen committed
144
Developer Legacy Notes
145
--------------------------------------------------------------------------------
Lambert Theisen's avatar
Lambert Theisen committed
146

Lambert Theisen's avatar
Lambert Theisen committed
147
148
149
Developer Tips
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

150
151
152
153
154
155
- Monitor the performance of the program with e.g.:

    .. code-block:: bash

        htop -p `{ python3 ../../src/fenicsR13.py inputs/1_coeffs_nosources_norot_inflow_p1p1p1p1p1_stab.yml > /dev/null & } && echo $!`

Lambert Theisen's avatar
Lambert Theisen committed
156
- Use doctest with ``python3 -m doctest -v src/meshes.py``
157
- Run ``pydocstyle`` once in a while
Lambert Theisen's avatar
Lambert Theisen committed
158
159
160
161
162
- Matplotbib fails when having wrong backend on macOS
    - Fix: Add ``backend: TkAgg`` to ``~/.matplotlib/matplotlibrc`` file
- Performance in Docker is way better than conda build, especially JIT compilation is faster
- Get C++ inlcude paths: ``echo | gcc -E -Wp,-v -``
- Bessel functions in DOLFIN:
163
    - C++17 functions cannpot be used. Boost functions also not per default. ``Expression("boost::math::cyl_bessel_i(0,atan2(x[1], x[0]))", degree=2)`` is allowed if one changes in file ``/usr/local/lib/python3.6/dist-packages/dolfin/jit/jit.py``
Lambert Theisen's avatar
Lambert Theisen committed
164

165
166
167
168
169
170
171
        .. code-block:: python

            _math_header = """
            // cmath functions
            #include <boost/math/special_functions/bessel.hpp> // Added
            %s
            """
Lambert Theisen's avatar
Lambert Theisen committed
172

173
174
Python notes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Lambert Theisen's avatar
Lambert Theisen committed
175
176

- Get current work directory:
Lambert Theisen's avatar
Lambert Theisen committed
177

178
    .. code-block:: python
Lambert Theisen's avatar
Lambert Theisen committed
179

180
181
182
        import os
        cwd = os.getcwd()
        print(cwd)
Lambert Theisen's avatar
Lambert Theisen committed
183

Lambert Theisen's avatar
Lambert Theisen committed
184
- Latex font for matplotlib:
Lambert Theisen's avatar
Lambert Theisen committed
185

186
    .. code-block:: python
Lambert Theisen's avatar
Lambert Theisen committed
187

188
189
190
191
        # LaTeX text fonts:
        # Use with raw strings: r"$\mathcal{O}(h^1)$"
        plt.rc('text', usetex=True)
        plt.rc('font', family='serif')
192

Lambert Theisen's avatar
Lambert Theisen committed
193
- Get system path where modules are searched:
194

195
    .. code-block:: python
196

197
198
        import sys
        print(sys.path)
Lambert Theisen's avatar
Lambert Theisen committed
199

200
201
202
203
Create new version tag
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1. Add CHANGELOG entry
2. Adapt version in `conf.py` for docs
Lambert Theisen's avatar
Lambert Theisen committed
204
3. Change badge in ``README.rst``
Lambert Theisen's avatar
Lambert Theisen committed
205
4. Change version in program information printing
206

207
208
209
210
211
212
213
214
215
216
Gitlab CI Setup
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- The ``build`` stage has to be triggered manually when something in the setup changes. This is because it takes a fair amount of time.
- In ``~/.gitlab-runner/config.toml`` (for the runner):
    - change priviliges to true
    - Use local images: ``pull_policy = "if-not-present"``
    - To ``[[runners]]`` add ``environment = ["DOCKER_TLS_CERTDIR="]`` (See https://gitlab.com/gitlab-org/gitlab-ce/issues/64959)
- Run local: ``gitlab-runner exec docker --docker-privileged build`` or with ``build`` replaced by job name
    - maybe local vars have to be change to use local Docker images because ``CI_REGISTRY``,... are not set

Lambert Theisen's avatar
Lambert Theisen committed
217
An example gitlab runner ``config/toml`` in ``~/.gitlab-runner`` can look like:
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238

.. code-block:: toml

    concurrent = 1
    check_interval = 0

    [[runners]]
    name = "190716-macbookpro"
    url = "https://git.rwth-aachen.de/"
    token = "<PRIVATE_TOKEN>"
    executor = "docker"
    environment = ["DOCKER_TLS_CERTDIR="]
    [runners.docker]
        tls_verify = false
        image = "docker:stable"
        privileged = true
        disable_cache = false
        volumes = ["/cache"]
        shm_size = 0
        pull_policy = "if-not-present"
    [runners.cache]
Lambert Theisen's avatar
Lambert Theisen committed
239

Lambert Theisen's avatar
Lambert Theisen committed
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
macOS Native FEniCS Installation (not recommended)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

#. Install ``miniconda`` from `here <https://conda.io/projects/conda/en/latest/user-guide/install/macos.html>`_
    #. If using ``zsh``, add miniconda bins to PATH: ``export PATH="$HOME/ miniconda3/bin:$PATH"`` to ``~/.zshrc``
    #. Maybe, activation has to be done with executing ``<path to  miniconda>/bin/activate``
    #. Optional: Create separate coda environment: ``conda creafenics-env``
#. Install FEniCS using conda: ``conda install -c conda-forge fenics``
    #. Optional: Install ``matplobib``: ``conda install -c conda-forge  matplotlib``
    #. Optional: Install ``meshio``: ``conda install -c mrossi meshio``
    #. Optional (for linting): ``conda install pylint``
    #. Install mshr with ``conda install -c conda-forge mshr``
    #. Fix macOS bug in matplotbib: ``mkdir -p ~/.matplotlib; echo  "backend: TkAgg" > ~/.matplotlib/matplotlibrc``
    #. XCode and command line developer tools msut be installed!
    #. Optional: Install Jupyter: ``conda install -c anaconda jupyter``
    #. Optional: Install documentation system: ``conda install -c anaconda  sphinx``
    #. Optional: ``conda install -c anaconda sympy``

Further Installation Tips
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**Interactive Jupyter Notebooks with Microsoft's Visual Studio Code**

This is the most convenient solution.
Run a file with ``%run ../../src/fenicsr13.py``

**X11 Window Forwarding on OSX**

See guide_ for the programs to install. Then source the ``open-macos-gui-tunnel.sh`` with ``. open-macos-gui-tunnel``. Afterwards, start the container and run the ``change-matplotbib-backend-tkagg.sh`` script to set the right ``matplotlib``'s output.

.. _guide: http://joshuamccall.com/articles/docker.html

**X11 Window Forwarding on Windows**

A nice guide can be found `here on Dev.to`_.

.. _`here on Dev.to`: https://dev.to/darksmile92/run-gui-app-in-linux-docker-container-on-windows-host-4kde

The steps can be summarized as:

1. Install the package manager `Chocolatey`_.

    .. code-block:: dosbatch

        REM comment: open cmd.exe as admin
        @"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -InputFormat None -ExecutionPolicy Bypass -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))" && SET "PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin"

2. Open ``cmd.exe`` as admin and install `VcXsrv Windows X Server`_.

    .. code-block:: bash

        choco install vcxsrv
3. Open a X11 server and set the ``ip`` variable (that is used in the ``docker-compose.yml`` when starting the Docker container to set ``export DISPLAY=${ip}:0``).

    .. code-block:: bash

        # home of this repo
        source sripts/open-windows-gui-tunnel.sh

.. _`Chocolatey`: https://chocolatey.org/
.. _`VcXsrv Windows X Server`: https://sourceforge.net/projects/vcxsrv/

Lambert Theisen's avatar
Lambert Theisen committed
302
Contact
Lambert Theisen's avatar
Lambert Theisen committed
303
--------------------------------------------------------------------------------
Lambert Theisen's avatar
Lambert Theisen committed
304
305
306
307
308
309

:Author:
    | Lambert Theisen
    | lambert.theisen@rwth-aachen.de
:Supervisor:
    | Prof. Dr. Manuel Torrilhon
Lambert Theisen's avatar
Lambert Theisen committed
310
    | Lehrstuhl für Mathematik (MathCCES)
Lambert Theisen's avatar
Lambert Theisen committed
311
312
313
314
315
316
317
    | RWTH Aachen University
    | mt@mathcces.rwth-aachen.de
:Context:
    | Masterthesis Computational Engineering Science
    | RWTH Aachen University
    | *Simulation of Non-Equilibrium Gas Flows Using the FEniCS Computing Platform*

318
319
.. |pipeline| image:: https://git.rwth-aachen.de/lamboo/fenicsR13/badges/master/pipeline.svg
    :target: https://git.rwth-aachen.de/lamboo/fenicsR13/commits/master
Lambert Theisen's avatar
Lambert Theisen committed
320
321
    :alt: Pipeline status

322
.. |coverage| image:: https://git.rwth-aachen.de/lamboo/fenicsR13/badges/master/coverage.svg
Lambert Theisen's avatar
Lambert Theisen committed
323
    :target: https://git.rwth-aachen.de/lamboo/fenicsR13/pipelines
Lambert Theisen's avatar
Lambert Theisen committed
324
    :alt: Test coverage
325

Lambert Theisen's avatar
Lambert Theisen committed
326
.. |version| image:: https://img.shields.io/badge/version-v1.0-blue.svg
Lambert Theisen's avatar
Lambert Theisen committed
327
    :target: https://git.rwth-aachen.de/lamBOO/fenicsR13/-/tags
328
    :alt: Documentation Website
329

330
.. |website| image:: https://img.shields.io/badge/doc-https%3A%2F%2Flamboo.pages.rwth--aachen.de%2FfenicsR13%2F-blue.svg
Lambert Theisen's avatar
Lambert Theisen committed
331
    :target: https://lamboo.pages.rwth-aachen.de/fenicsR13/
332
    :alt: Documentation Website