.flake8

 [flake8]
 max-line-length=120
-exclude=lbmpy/plot.py
-        lbmpy/session.py
-ignore = W293 W503 W291 E741
+exclude=src/lbmpy/plot.py
+        src/lbmpy/session.py
+ignore = W293 W503 W291 C901 E741

.gitattributes

-lbmpy/_version.py export-subst
+src/lbmpy/_version.py export-subst

.gitignore

 __pycache__
 .ipynb_checkpoints
-.coverage
+.coverage*
 *.pyc
 *.vti
 /build
 /html_doc
 /dist
-/*.egg-info
+*.egg-info
 .cache
 _build
 /.idea
@@ -15,14 +15,18 @@ _local_tmp
 **/pylintrc
 *.bak
 *.tmp
-/lbmpy_tests/db
+/tests/db
 doc/bibtex.json
 /db
-/lbmpy/phasefield/simplex_projection.*.so
-/lbmpy/phasefield/simplex_projection.c
+/src/lbmpy/phasefield/simplex_projection.*.so
+/src/lbmpy/phasefield/simplex_projection.c
+
+test-report
+report.xml
 
 # macOS
 **/.DS_Store
+*.uuid
 
 # benchmark database
-/lbmpy_tests/benchmark/db
\ No newline at end of file
+/tests/benchmark/db
\ No newline at end of file

.gitlab-ci.yml

 stages:
-  - pretest
-  - test
+  - "Code Quality"
+  - "Tests"
+  - "Prerelease-Tests"
+  - integration
+  - nightly
+  - docs
   - deploy
 
+# --------------------------  Code Quality --------------------------------------------------------------------------------
 
-# --------------------------  Pre Tests --------------------------------------------------------------------------------
+
+# Linter for code formatting
+flake8-lint:
+  stage: "Code Quality"
+  image: i10git.cs.fau.de:5005/pycodegen/pycodegen/nox:alpine
+  script:
+    - nox -s lint
+  tags:
+    - docker
+
+
+# --------------------------  Tests --------------------------------------------------------------------------------
 
 # Normal test - runs on every commit all but "long run" tests
-tests-and-coverage:
-  stage: pretest
-  except:
-    variables:
-      - $ENABLE_NIGHTLY_BUILDS
-  image: i10git.cs.fau.de:5005/pycodegen/pycodegen/full
+testsuite-cuda-py3.10:
+  stage: "Tests"
+  image: i10git.cs.fau.de:5005/pycodegen/pycodegen/nox:ubuntu24.04-cuda12.6
+  needs: []
   script:
-    # - pip install sympy --upgrade
-    - export NUM_CORES=$(nproc --all)
     - mkdir -p ~/.config/matplotlib
     - echo "backend:template" > ~/.config/matplotlib/matplotlibrc
-    - mkdir public
-    - pip install git+https://gitlab-ci-token:${CI_JOB_TOKEN}@i10git.cs.fau.de/pycodegen/pystencils.git@master#egg=pystencils
-    - env
-    - pip list
-    - py.test -v -n $NUM_CORES --cov-report html --cov-report term --cov=. -m "not longrun" --junitxml=report.xml
-    - python3 -m coverage xml
+    - nox -s "testsuite_gpu-3.10(cupy12)"
   tags:
     - docker
-    - cuda11
+    - cuda
+    - cudaComputeCapability6.1
     - AVX
   coverage: /Total coverage:\s\d+.\d+\%/
   artifacts:
     when: always
     paths:
       - coverage_report
+      - test-report
     reports:
       coverage_report:
         coverage_format: cobertura
         path: coverage.xml
       junit: report.xml
 
+
+testsuite-cpu-py3.13:
+  stage: "Tests"
+  image: i10git.cs.fau.de:5005/pycodegen/pycodegen/nox:alpine
+  needs: []
+  script:
+    - mkdir -p ~/.config/matplotlib
+    - echo "backend:template" > ~/.config/matplotlib/matplotlibrc
+    - nox -s "testsuite_cpu-3.13"
+  tags:
+    - docker
+    - AVX
+  artifacts:
+    when: always
+    paths:
+      - test-report
+    reports:
+      junit: report.xml
+
+
 # Normal test with longruns
 tests-and-coverage-with-longrun:
-  stage: test
+  stage: "Tests"
   when: manual
   allow_failure: true
   image: i10git.cs.fau.de:5005/pycodegen/pycodegen/full
@@ -57,161 +86,120 @@ tests-and-coverage-with-longrun:
     - py.test -v -n $NUM_CORES
   tags:
     - docker
-    - cuda11
+    - cuda
+    - cudaComputeCapability6.1
     - AVX
 
-minimal-conda:
-  stage: pretest
-  except:
-    variables:
-      - $ENABLE_NIGHTLY_BUILDS
-  image: i10git.cs.fau.de:5005/pycodegen/pycodegen/minimal_conda
-  script:
-    - pip install git+https://gitlab-ci-token:${CI_JOB_TOKEN}@i10git.cs.fau.de/pycodegen/pystencils.git@master#egg=pystencils
-    - python setup.py quicktest
-  tags:
-    - docker
+# --------------------------  Nightly and Pre-Release Tests --------------------------------------------------------------------------------
 
-# Linter for code formatting
-flake8-lint:
-  stage: pretest
-  except:
-    variables:
-      - $ENABLE_NIGHTLY_BUILDS
-  image: i10git.cs.fau.de:5005/pycodegen/pycodegen/full
-  script:
-    - flake8 lbmpy
-  tags:
-    - docker
-    - cuda11
-
-# -------------------------- Tests -------------------------------------------------------------------------------------
-
-# pipeline with latest python version
-latest-python:
-  stage: test
-  except:
-    variables:
-      - $ENABLE_NIGHTLY_BUILDS
-  image: i10git.cs.fau.de:5005/pycodegen/pycodegen/latest_python
-  before_script:
-    - pip install git+https://gitlab-ci-token:${CI_JOB_TOKEN}@i10git.cs.fau.de/pycodegen/pystencils.git@master#egg=pystencils
+# Test against latest pystencils 2.0 development version
+pystencils-2.0dev:
+  stage: "Prerelease-Tests"
+  image: i10git.cs.fau.de:5005/pycodegen/pycodegen/nox:ubuntu24.04-cuda12.6
+  allow_failure: true
+  needs: []
   script:
-    - env
-    - pip list
-    - export NUM_CORES=$(nproc --all)
     - mkdir -p ~/.config/matplotlib
     - echo "backend:template" > ~/.config/matplotlib/matplotlibrc
-    - mkdir public
-    - py.test -v -n $NUM_CORES -m "not longrun" --junitxml=report.xml
+    - nox -s "testsuite_pystencils2(cupy12)"
   tags:
     - docker
     - AVX
+    - cuda
+    - cudaComputeCapability6.1
   artifacts:
     when: always
+    paths:
+      - test-report
     reports:
       junit: report.xml
 
-# Minimal tests in windows environment
-minimal-windows:
-  stage: test
-  except:
-    variables:
-      - $ENABLE_NIGHTLY_BUILDS
-  tags:
-    - win
-  script:
-    - export NUM_CORES=$(nproc --all)
-    - export MPLBACKEND=Agg
-    - source /cygdrive/c/Users/build/Miniconda3/Scripts/activate
-    - source activate pystencils
-    - pip install git+https://gitlab-ci-token:${CI_JOB_TOKEN}@i10git.cs.fau.de/pycodegen/pystencils.git@master#egg=pystencils
-    - python -c "import numpy"
-    - pip install sympy==1.9
-    - py.test -v -m "not (notebook or longrun)"
-
 minimal-sympy-master:
-  stage: test
-  except:
-    variables:
-      - $ENABLE_NIGHTLY_BUILDS
-  image: i10git.cs.fau.de:5005/pycodegen/pycodegen/minimal_conda
+  stage: "Prerelease-Tests"
+  needs: []
+  image: i10git.cs.fau.de:5005/pycodegen/pycodegen/nox:alpine
   script:
-    - pip install git+https://gitlab-ci-token:${CI_JOB_TOKEN}@i10git.cs.fau.de/pycodegen/pystencils.git@master#egg=pystencils
-    - python -m pip install --upgrade git+https://github.com/sympy/sympy.git
-    - pip list
-    - python setup.py quicktest
+    - nox -s quicktest -P 3.13 -- --sympy-master
   allow_failure: true
   tags:
     - docker
-    - cuda
 
-ubuntu:
-  stage: test
-  except:
-    variables:
-      - $ENABLE_NIGHTLY_BUILDS
-  image: i10git.cs.fau.de:5005/pycodegen/pycodegen/ubuntu
+# pycodegen-integration:
+#   image: i10git.cs.fau.de:5005/pycodegen/pycodegen/full
+#   stage: integration
+#   when: manual
+#   allow_failure: true
+#   script:
+#     - env
+#     - pip list
+#     - git clone https://gitlab-ci-token:${CI_JOB_TOKEN}@i10git.cs.fau.de/pycodegen/pycodegen.git
+#     - cd pycodegen
+#     - git submodule sync --recursive
+#     - git submodule update --init --recursive
+#     - git submodule foreach git fetch origin   # compare the latest master version!
+#     - git submodule foreach git reset --hard origin/master
+#     - cd lbmpy
+#     - git remote add test $CI_REPOSITORY_URL
+#     - git fetch test
+#     - git reset --hard $CI_COMMIT_SHA
+#     - cd ..
+#     - pip install -e pystencils/
+#     - pip install -e lbmpy/
+#     - ./install_walberla.sh
+#     # build all integration tests
+#     - cd walberla/build/
+#     - make -j $NUM_CORES MicroBenchmarkGpuLbm LbCodeGenerationExample
+#     - cd apps/benchmarks/UniformGridGPU
+#     - make -j $NUM_CORES
+#     - cd ../UniformGridCPU
+#     - make -j $NUM_CORES
+
+#   tags:
+#     - docker
+#     - cuda
+#     - cudaComputeCapability6.1
+#     - AVX
+
+
+# -------------------- Scheduled Tasks --------------------------------------------------------------------------
+
+
+nightly-sympy:
+  stage: nightly
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "schedule"
+  image: i10git.cs.fau.de:5005/pycodegen/pycodegen/latest_python
   before_script:
-    # - apt-get -y remove python3-sympy
-    - ln -s /usr/include/locale.h /usr/include/xlocale.h
-    # - pip3 install `grep -Eo 'sympy[>=]+[0-9\.]+' setup.py | sed 's/>/=/g'`
-    - pip3 install git+https://gitlab-ci-token:${CI_JOB_TOKEN}@i10git.cs.fau.de/pycodegen/pystencils.git@master#egg=pystencils
+    - pip install -e .
+    - pip install git+https://gitlab-ci-token:${CI_JOB_TOKEN}@i10git.cs.fau.de/pycodegen/pystencils.git@master#egg=pystencils
+    - pip install --upgrade --pre sympy
   script:
+    - env
+    - pip list
     - export NUM_CORES=$(nproc --all)
     - mkdir -p ~/.config/matplotlib
     - echo "backend:template" > ~/.config/matplotlib/matplotlibrc
-    - env
-    - pip3 list
-    - pytest-3 -v -n $NUM_CORES -m "not longrun" --junitxml=report.xml
+    - mkdir public
+    - pytest -v -n $NUM_CORES -m "not longrun" --junitxml=report.xml
   tags:
     - docker
-    - cuda11
+    - AVX
+    - cuda
+    - cudaComputeCapability6.1
   artifacts:
     when: always
     reports:
       junit: report.xml
 
-pycodegen-integration:
-  image: i10git.cs.fau.de:5005/pycodegen/pycodegen/full
-  stage: test
-  when: manual
-  allow_failure: true
-  script:
-    - env
-    - pip list
-    - git clone https://gitlab-ci-token:${CI_JOB_TOKEN}@i10git.cs.fau.de/pycodegen/pycodegen.git
-    - cd pycodegen
-    - git submodule sync --recursive
-    - git submodule update --init --recursive
-    - git submodule foreach git fetch origin   # compare the latest master version!
-    - git submodule foreach git reset --hard origin/master
-    - cd lbmpy
-    - git remote add test $CI_REPOSITORY_URL
-    - git fetch test
-    - git reset --hard $CI_COMMIT_SHA
-    - cd ..
-    - pip install -e pystencils/
-    - pip install -e lbmpy/
-    - ./install_walberla.sh
-    # build all integration tests
-    - cd walberla/build/
-    - make -j $NUM_CORES MicroBenchmarkGpuLbm LbCodeGenerationExample
-    - cd apps/benchmarks/UniformGridGPU
-    - make -j $NUM_CORES
-    - cd ../UniformGridCPU
-    - make -j $NUM_CORES
-
-  tags:
-    - docker
-    - cuda11
-    - AVX
 
 # -------------------- Documentation and deploy ------------------------------------------------------------------------
 
 build-documentation:
-  stage: test
+  stage: docs
+  needs: []
   image: i10git.cs.fau.de:5005/pycodegen/pycodegen/documentation
+  before_script:
+    - pip install -e .
   script:
     - export PYTHONPATH=`pwd`
     - pip install git+https://gitlab-ci-token:${CI_JOB_TOKEN}@i10git.cs.fau.de/pycodegen/pystencils.git@master#egg=pystencils
@@ -219,7 +207,8 @@ build-documentation:
     - sphinx-build -W -b html doc html_doc
   tags:
     - docker
-    - cuda11
+    - cuda
+    - cudaComputeCapability6.1
   artifacts:
     paths:
       - html_doc
@@ -227,7 +216,10 @@ build-documentation:
 
 pages:
   image: i10git.cs.fau.de:5005/pycodegen/pycodegen/full
+  rules:
+    - if: '$CI_PIPELINE_SOURCE != "schedule" && $CI_PROJECT_PATH == "pycodegen/lbmpy" && $CI_COMMIT_BRANCH == "master"'
   stage: deploy
+  needs: ["testsuite-cuda-py3.10", "build-documentation"]
   script:
     - ls -l
     - mv coverage_report html_doc
@@ -237,5 +229,3 @@ pages:
       - public
   tags:
     - docker
-  only:
-    - master@pycodegen/lbmpy

AUTHORS.txt

@@ -11,3 +11,4 @@ Contributors:
   - Rudolf Weeber <weeber@icp.uni-stuttgart.de>
   - Christian Godenschwager <christian.godenschwager@fau.de>
   - Jan Hönig <jan.hoenig@fau.de>
+  - Philipp Suffa <philipp.suffa@fau.de>

COPYING.txt

-------------------------   Important ---------------------------------
-
-lbmpy is under the following GNU AGPLv3 license. 
-This license holds for the sources of lbmpy itself as well 
-as for all kernels generated with lbmpy i.e. 
-the output of lbmpy is also protected by the GNU AGPLv3 license. 
-
-----------------------------------------------------------------------
-
-
-
-                    
                     GNU AFFERO GENERAL PUBLIC LICENSE
                        Version 3, 19 November 2007
 

MANIFEST.in

-include README.md
-include COPYING.txt
 include AUTHORS.txt
 include CONTRIBUTING.md
-global-include *.pyx
-include versioneer.py
-include lbmpy/_version.py
+include CHANGELOG.md

README.md

@@ -71,6 +71,7 @@ Many thanks go to the [contributors](https://i10git.cs.fau.de/pycodegen/lbmpy/-/
 If you use lbmpy in a publication, please cite the following articles:
 
 Overview:
+  - F. Hennig et al, Advanced Automatic Code Generation for Multiple Relaxation-Time Lattice Boltzmann Methods. SIAM Journal on Scientific Computing, 2023. https://doi.org/10.1137/22M1531348 ([Preprint](https://arxiv.org/abs/2211.02435))
   - M. Bauer et al, lbmpy: Automatic code generation for efficient parallel lattice Boltzmann methods. Journal of Computational Science, 2021. https://doi.org/10.1016/j.jocs.2020.101269 ([Preprint](https://arxiv.org/abs/2001.11806))
 
 Multiphase:

binder/environment.yml

@@ -7,7 +7,7 @@
 #     conda env create -f conda_environment_user.yml
 #     . activate pystencils
 #
-# If you have CUDA installed and want to use your GPU, uncomment the last line to install pycuda
+# If you have CUDA or ROCm installed and want to use your GPU, uncomment the last line to install cupy
 #
 # ----------------------------------------------------------------------------------------------------------------------
 
@@ -33,4 +33,4 @@ dependencies:
       - pyevtk # VTK output for serial simulations
       - blitzdb # file-based No-SQL database to store simulation results
       - pystencils
-      #- pycuda # add this if you have CUDA installed
+      #- cupy # add this if you have CUDA or ROCm installed

conftest.py

@@ -5,13 +5,18 @@ import runpy
 import sys
 import warnings
 import platform
+import pathlib
 
 import nbformat
-from nbconvert import PythonExporter
+import nbconvert
 import sympy
+
+from lbmpy._compat import IS_PYSTENCILS_2
+
 # Trigger config file reading / creation once - to avoid race conditions when multiple instances are creating it
 # at the same time
-from pystencils.cpu import cpujit
+if not IS_PYSTENCILS_2:
+    from pystencils.cpu import cpujit
 
 # trigger cython imports - there seems to be a problem when multiple processes try to compile the same cython file
 # at the same time
@@ -19,9 +24,9 @@ try:
     import pyximport
 
     pyximport.install(language_level=3)
+    from lbmpy.phasefield.simplex_projection import simplex_projection_2d  # NOQA
 except ImportError:
     pass
-from lbmpy.phasefield.simplex_projection import simplex_projection_2d  # NOQA
 
 SCRIPT_FOLDER = os.path.dirname(os.path.realpath(__file__))
 sys.path.insert(0, os.path.abspath('lbmpy'))
@@ -42,33 +47,42 @@ def add_path_to_ignore(path):
 
 collect_ignore = [os.path.join(SCRIPT_FOLDER, "doc", "conf.py"),
                   os.path.join(SCRIPT_FOLDER, "doc", "img", "mb_discretization", "maxwell_boltzmann_stencil_plot.py")]
-add_path_to_ignore('pystencils_tests/benchmark')
 add_path_to_ignore('_local_tmp')
 
+if IS_PYSTENCILS_2:
+    #   TODO: Fix these step-by-step
+    collect_ignore += [
+        os.path.join(SCRIPT_FOLDER, "doc", "notebooks", "10_tutorial_conservative_allen_cahn_two_phase.ipynb"),
+        os.path.join(SCRIPT_FOLDER, "tests", "test_compiled_in_boundaries.ipynb")
+    ]
+
 try:
-    import pycuda
+    import cupy
 except ImportError:
-    collect_ignore += [os.path.join(SCRIPT_FOLDER, "lbmpy_tests/test_cpu_gpu_equivalence.py")]
+    collect_ignore += [os.path.join(SCRIPT_FOLDER, "tests/test_cpu_gpu_equivalence.py")]
 
 try:
     import waLBerla
 except ImportError:
-    collect_ignore += [os.path.join(SCRIPT_FOLDER, "lbmpy_tests/test_datahandling_parallel.py")]
+    collect_ignore += [os.path.join(SCRIPT_FOLDER, "tests/test_datahandling_parallel.py")]
 
 try:
     import blitzdb
 except ImportError:
-    collect_ignore += [os.path.join(SCRIPT_FOLDER, "lbmpy_tests/benchmark"),
+    collect_ignore += [os.path.join(SCRIPT_FOLDER, "tests/benchmark"),
                        os.path.join(SCRIPT_FOLDER,
-                                    "lbmpy_tests/full_scenarios/kida_vortex_flow/scenario_kida_vortex_flow.py")]
+                                    "tests/full_scenarios/kida_vortex_flow/scenario_kida_vortex_flow.py"),
+                       os.path.join(SCRIPT_FOLDER, "tests/full_scenarios/shear_wave/scenario_shear_wave.py"),
+                       os.path.join(SCRIPT_FOLDER, "tests/test_json_serializer.py"),
+                       os.path.join(SCRIPT_FOLDER, "src/lbmpy/db.py")]
 
 if platform.system().lower() == 'windows':
-    collect_ignore += [os.path.join(SCRIPT_FOLDER, "lbmpy_tests/test_quicktests.py")]
+    collect_ignore += [os.path.join(SCRIPT_FOLDER, "tests/test_quicktests.py")]
 
 sver = sympy.__version__.split(".")
 if int(sver[0]) == 1 and int(sver[1]) < 2:
-    add_path_to_ignore('lbmpy_tests/phasefield')
-    collect_ignore += [os.path.join(SCRIPT_FOLDER, "lbmpy_tests/test_n_phase_boyer_noncoupled.ipynb")]
+    add_path_to_ignore('tests/phasefield')
+    collect_ignore += [os.path.join(SCRIPT_FOLDER, "tests/test_n_phase_boyer_noncoupled.ipynb")]
 
 collect_ignore += [os.path.join(SCRIPT_FOLDER, 'setup.py')]
 
@@ -104,22 +118,29 @@ class IPyNbTest(pytest.Item):
 
         # disable matplotlib output
         exec("import matplotlib.pyplot as p; "
+             "p.close('all'); "
              "p.switch_backend('Template')", global_dict)
 
         # in notebooks there is an implicit plt.show() - if this is not called a warning is shown when the next
         # plot is created. This warning is suppressed here
+        # Also animations cannot be shown, which also leads to a warning.
         exec("import warnings;"
-             "warnings.filterwarnings('ignore', 'Adding an axes using the same arguments as a previous.*');",
+             "warnings.filterwarnings('ignore', 'Adding an axes using the same arguments as a previous.*');"
+             "warnings.filterwarnings('ignore', 'Animation was deleted without rendering anything.*');",
              global_dict)
         with tempfile.NamedTemporaryFile() as f:
             f.write(self.code.encode())
             f.flush()
             runpy.run_path(f.name, init_globals=global_dict, run_name=self.name)
 
+        #   Close any open figures
+        exec("import matplotlib.pyplot as p; "
+             "p.close('all')", global_dict)
+
 
 class IPyNbFile(pytest.File):
     def collect(self):
-        exporter = PythonExporter()
+        exporter = nbconvert.PythonExporter()
         exporter.exclude_markdown = True
         exporter.exclude_input_prompt = True
 
@@ -138,10 +159,19 @@ class IPyNbFile(pytest.File):
         pass
 
 
-def pytest_collect_file(path, parent):
-    glob_exprs = ["*demo*.ipynb", "*tutorial*.ipynb", "test_*.ipynb"]
-    if any(path.fnmatch(g) for g in glob_exprs):
-        if pytest_version >= 50403:
-            return IPyNbFile.from_parent(fspath=path, parent=parent)
-        else:
-            return IPyNbFile(path, parent)
+if pytest_version >= 70000:
+    #   Since pytest 7.0, usage of `py.path.local` is deprecated and `pathlib.Path` should be used instead
+    import pathlib
+
+    def pytest_collect_file(file_path: pathlib.Path, parent):
+        glob_exprs = ["*demo*.ipynb", "*tutorial*.ipynb", "test_*.ipynb"]
+        if any(file_path.match(g) for g in glob_exprs):
+            return IPyNbFile.from_parent(path=file_path, parent=parent)
+else:
+    def pytest_collect_file(path, parent):
+        glob_exprs = ["*demo*.ipynb", "*tutorial*.ipynb", "test_*.ipynb"]
+        if any(path.fnmatch(g) for g in glob_exprs):
+            if pytest_version >= 50403:
+                return IPyNbFile.from_parent(fspath=path, parent=parent)
+            else:
+                return IPyNbFile(path, parent)

doc/conf.py

@@ -33,7 +33,7 @@ version = re.sub(r'(\d+\.\d+)\.\d+(.*)', r'\1\2', lbmpy.__version__)
 version = re.sub(r'(\.dev\d+).*?$', r'\1', version)
 # The full version, including alpha/beta/rc tags.
 release = lbmpy.__version__
-language = None
+language = 'en'
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '**.ipynb_checkpoints']
 default_role = 'any'
 pygments_style = 'sphinx'

doc/img/logo.svg

@@ -2,23 +2,23 @@
 <!-- Created with Inkscape (http://www.inkscape.org/) -->
 
 <svg
-   xmlns:dc="http://purl.org/dc/elements/1.1/"
-   xmlns:cc="http://creativecommons.org/ns#"
-   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
-   xmlns:svg="http://www.w3.org/2000/svg"
-   xmlns="http://www.w3.org/2000/svg"
-   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
-   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
    width="53.913788mm"
    height="53.913788mm"
    viewBox="0 0 53.913788 53.913788"
    version="1.1"
    id="svg834"
-   inkscape:version="0.92.3 (2405546, 2018-03-11)"
+   inkscape:version="1.4.2 (ebf0e940d0, 2025-05-08)"
    sodipodi:docname="logo.svg"
    inkscape:export-filename="/local/bauer/code/lbmpy/lbmpy/doc/img/logo.png"
    inkscape:export-xdpi="70.669998"
-   inkscape:export-ydpi="70.669998">
+   inkscape:export-ydpi="70.669998"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:dc="http://purl.org/dc/elements/1.1/">
   <defs
      id="defs828">
     <marker
@@ -641,25 +641,31 @@
      inkscape:pageopacity="0.0"
      inkscape:pageshadow="2"
      inkscape:zoom="1.4"
-     inkscape:cx="158.26067"
-     inkscape:cy="-4.9825309"
+     inkscape:cx="158.21429"
+     inkscape:cy="251.78571"
      inkscape:document-units="mm"
      inkscape:current-layer="layer1"
      showgrid="false"
-     inkscape:window-width="1214"
-     inkscape:window-height="1052"
-     inkscape:window-x="1482"
-     inkscape:window-y="524"
+     inkscape:window-width="1557"
+     inkscape:window-height="1122"
+     inkscape:window-x="0"
+     inkscape:window-y="0"
      inkscape:window-maximized="0"
      fit-margin-top="0"
      fit-margin-left="0"
      fit-margin-right="0"
-     fit-margin-bottom="0">
+     fit-margin-bottom="0"
+     inkscape:showpageshadow="0"
+     inkscape:pagecheckerboard="1"
+     inkscape:deskcolor="#d1d1d1">
     <inkscape:grid
        type="xygrid"
        id="grid1886"
        originx="-9.8407853"
-       originy="-227.28709" />
+       originy="-227.28709"
+       spacingy="1"
+       spacingx="1"
+       units="mm" />
   </sodipodi:namedview>
   <metadata
      id="metadata831">
@@ -688,21 +694,11 @@
        ry="3.0735996"
        inkscape:export-xdpi="188.45"
        inkscape:export-ydpi="188.45" />
-    <text
-       xml:space="preserve"
-       style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:2.11666656px;line-height:125%;font-family:'Latin Modern Mono Light';-inkscape-font-specification:'Latin Modern Mono Light, ';letter-spacing:0px;word-spacing:0px;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
-       x="13.547134"
-       y="63.204773"
+    <path
+       style="font-weight:bold;font-size:16.9333px;line-height:125%;font-family:'Latin Modern Mono Light';-inkscape-font-specification:'Latin Modern Mono Light, Bold';letter-spacing:0px;word-spacing:0px;fill:#ffffff;stroke-width:0.264583px"
+       d="m 21.505785,62.578241 c 0,-0.626532 -0.474132,-0.643466 -0.795865,-0.643466 h -2.015062 v -8.26345 c 0,-0.609599 -0.118533,-0.812798 -0.795865,-0.812798 h -2.607729 c -0.321732,0 -0.812798,0.01693 -0.812798,0.643465 0,0.609599 0.507999,0.626532 0.795865,0.626532 h 2.015063 v 7.806251 h -1.99813 c -0.321732,0 -0.812798,0.01693 -0.812798,0.643466 0,0.609599 0.507999,0.626532 0.795865,0.626532 h 5.435589 c 0.3048,0 0.795865,-0.01693 0.795865,-0.626532 z m 9.228643,-3.064927 c 0,-2.116663 -1.54093,-3.776126 -3.352793,-3.776126 -0.728132,0 -1.405464,0.237066 -1.964263,0.643465 v -2.709328 c 0,-0.609599 -0.118533,-0.812798 -0.795865,-0.812798 h -1.202265 c -0.321732,0 -0.812798,0.01693 -0.812798,0.643465 0,0.609599 0.507999,0.626532 0.795865,0.626532 h 0.609599 v 8.263451 c 0,0.406399 0.01693,0.812798 0.711198,0.812798 0.524933,0 0.660399,-0.237066 0.677332,-0.575732 0.643466,0.541865 1.303865,0.677332 1.79493,0.677332 1.862663,0 3.53906,-1.625597 3.53906,-3.793059 z m -1.388531,0 c 0,1.49013 -1.083731,2.523061 -2.184395,2.523061 -1.202265,0 -1.727197,-1.371597 -1.727197,-2.116662 v -1.202265 c 0,-0.914398 0.897465,-1.710263 1.862663,-1.710263 1.151464,0 2.048929,1.151465 2.048929,2.506129 z m 10.820373,3.064927 c 0,-0.558799 -0.321733,-0.643466 -0.931331,-0.643466 v -3.860792 c 0,-0.355599 -0.03387,-2.336795 -1.608664,-2.336795 -0.474132,0 -1.117598,0.186266 -1.608663,0.745065 -0.287867,-0.491066 -0.745066,-0.745065 -1.269998,-0.745065 -0.491066,0 -0.948265,0.169333 -1.337731,0.474132 -0.118533,-0.372533 -0.440265,-0.389466 -0.745065,-0.389466 h -0.524932 c -0.3048,0 -0.812799,0.03387 -0.812799,0.626532 0,0.558799 0.321733,0.643466 0.931332,0.643466 v 4.842923 c -0.609599,0 -0.931332,0.08467 -0.931332,0.643466 0,0.609599 0.524933,0.626532 0.812799,0.626532 h 1.43933 c 0.3048,0 0.761999,-0.01693 0.761999,-0.626532 0,-0.558799 -0.270933,-0.643466 -0.880532,-0.643466 v -2.827861 c 0,-1.354664 0.575732,-2.099729 1.219198,-2.099729 0.321733,0 0.474132,0.270933 0.474132,1.219198 v 3.708392 c -0.355599,0.01693 -0.677332,0.1016 -0.677332,0.643466 0,0.609599 0.474133,0.626532 0.761999,0.626532 h 1.236131 c 0.304799,0 0.761998,-0.01693 0.761998,-0.626532 0,-0.558799 -0.287866,-0.643466 -0.897465,-0.643466 v -2.827861 c 0,-1.354664 0.592666,-2.099729 1.219198,-2.099729 0.338666,0 0.474132,0.270933 0.474132,1.219198 v 3.708392 c -0.338666,0.01693 -0.660398,0.1016 -0.660398,0.643466 0,0.609599 0.474132,0.626532 0.745065,0.626532 h 1.236131 c 0.304799,0 0.812798,-0.01693 0.812798,-0.626532 z m 9.829776,-3.064927 c 0,-2.116663 -1.540931,-3.776126 -3.352794,-3.776126 -0.728132,0 -1.422397,0.237066 -1.981196,0.660398 -0.01693,-0.389466 -0.169333,-0.575732 -0.778932,-0.575732 H 42.68086 c -0.321733,0 -0.812798,0.03387 -0.812798,0.643466 0,0.609598 0.507999,0.626532 0.795865,0.626532 h 0.609598 v 8.500516 H 42.68086 c -0.321733,0 -0.812798,0.01693 -0.812798,0.643466 0,0.609598 0.507999,0.626532 0.795865,0.626532 h 2.624661 c 0.287866,0 0.795865,-0.01693 0.795865,-0.626532 0,-0.626532 -0.491065,-0.643466 -0.812798,-0.643466 h -0.592666 v -2.963327 c 0.643466,0.558799 1.286931,0.677332 1.777997,0.677332 1.862663,0 3.53906,-1.625597 3.53906,-3.793059 z m -1.388531,0 c 0,1.49013 -1.083731,2.523061 -2.184396,2.523061 -1.202264,0 -1.727196,-1.371597 -1.727196,-2.116662 v -1.202265 c 0,-0.914398 0.897465,-1.710263 1.862663,-1.710263 1.151464,0 2.048929,1.151465 2.048929,2.506129 z M 59.08922,56.46532 c 0,-0.626533 -0.474133,-0.643466 -0.795865,-0.643466 h -1.930397 c -0.304799,0 -0.795865,0.03387 -0.795865,0.626532 0,0.626532 0.474133,0.643466 0.795865,0.643466 h 0.270933 l -1.456264,4.419591 -1.676396,-4.419591 h 0.220133 c 0.304799,0 0.795865,-0.01693 0.795865,-0.626532 0,-0.626533 -0.474133,-0.643466 -0.795865,-0.643466 h -1.930397 c -0.321732,0 -0.795865,0.01693 -0.795865,0.643466 0,0.609598 0.491066,0.626532 0.795865,0.626532 H 52.2143 l 2.370662,5.977455 c -0.06773,0.186266 -0.423333,1.371597 -0.609599,1.744129 -0.338666,0.643466 -0.863598,1.032932 -1.185331,1.032932 0.01693,-0.06773 0.186266,-0.118533 0.186266,-0.372533 0,-0.491066 -0.355599,-0.846665 -0.846665,-0.846665 -0.524932,0 -0.846665,0.355599 -0.846665,0.846665 0,0.761999 0.609599,1.490131 1.490131,1.490131 1.69333,0 2.523062,-2.252129 2.590795,-2.438396 l 2.523061,-7.433718 h 0.4064 c 0.304799,0 0.795865,-0.01693 0.795865,-0.626532 z"
        id="text1392"
-       inkscape:export-xdpi="188.45"
-       inkscape:export-ydpi="188.45"><tspan
-         sodipodi:role="line"
-         id="tspan1390"
-         x="13.547134"
-         y="63.204773"
-         style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:16.93333244px;font-family:'Latin Modern Mono Light';-inkscape-font-specification:'Latin Modern Mono Light, Bold';fill:#ffffff;stroke-width:0.26458332px">lbm<tspan
-   style="font-size:2.82222223px"
-   id="tspan1398"> </tspan>py</tspan></text>
+       aria-label="lbm py" />
     <path
        style="fill:none;fill-rule:evenodd;stroke:#dddddd;stroke-width:0.84519458;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow1Send-8-6-9)"
        d="M 36.797679,33.475 H 23.568513"

doc/index.rst

@@ -6,6 +6,9 @@ lbmpy
     :maxdepth: 2
 
     sphinx/tutorials.rst
+    sphinx/methods.rst
+    sphinx/boundary_conditions.rst
+    sphinx/forcemodels.rst
     sphinx/api.rst
 
 

doc/notebooks/01_tutorial_predefinedScenarios.ipynb

 %% Cell type:code id: tags:
 ``` python
 import pytest
-pytest.importorskip('pycuda')
+pytest.importorskip('cupy')
 ```
 %% Output
-    <module 'pycuda' from '/home/markus/miniconda3/envs/pystencils/lib/python3.8/site-packages/pycuda/__init__.py'>
+    <module 'cupy' from '/home/markus/.local/lib/python3.11/site-packages/cupy/__init__.py'>
 %% Cell type:code id: tags:
 ``` python
 from lbmpy.session import *
 from pystencils import Target
 ```
 %% Cell type:markdown id: tags:
 # Tutorial 01: Running pre-defined scenarios
 *lbmpy* is a module to do Lattice Boltzmann simulations in Python.
 In this tutorial you will get a broad overview of *lbmpy*'s features. We will run some of the included scenarios that come with *lbmpy*, like a channel flow and a lid driven cavity. This tutorial uses the simple, high-level API of *lbmpy*, while the following tutorials go into the low-level details.
 The only prerequisite for this tutorial is basic Python and [numpy](http://www.numpy.org/) knowledge.
 > #### What's special about *lbmpy* ?
 > The LBM kernels (i.e. the functions that do all the computations) are not written in Python. Instead *lbmpy* generates optimized C or CUDA code for these kernels and compiles it using the *pystencils* module. In that way we get very fast LBM kernels, a lot faster than pure Python implementations and probably also faster than handwritten C kernels. This sounds complicated, but we don't have to care about all this background work, since all compiled kernels are available as Python functions again. Thus *lbmpy* can be used just like any other Python package.
 ## Lid Driven Cavity
 We start by simulating a fluid in a rectangular box, where one wall (the lid) is moving. This is called a 'lid driven cavity'. At the stationary walls *no-slip* boundary conditions are set, which enforce zero velocity at the wall. At the lid there is a *velocity bounce back (UBB)* boundary condition, which sets zero normal velocity and a prescribed tangential velocity.
 We don't have to set up all these boundary conditions manually since there is a function ``create_lid_driven_cavity``  that does all the work for us. This function takes the tangential velocity of the lid, which drives the flow. It is given in lattice units and to get a stable simulation it should be smaller than 0.1. The `relaxation_rate` determines the viscosity of the fluid: Small relaxation rates correspond to high viscosity. The `relaxation_rate` has to be between 0 and 2.
 %% Cell type:code id: tags:
 ``` python
 ldc_scenario = create_lid_driven_cavity(domain_size=(80,50), lid_velocity=0.01, relaxation_rate=1.95)
 ldc_scenario.method
 ```
 %% Output
     <lbmpy.methods.momentbased.momentbasedmethod.MomentBasedLbMethod at 0x7fe7a8828d30>
 %% Cell type:markdown id: tags:
 The *run* method of the scenario runs the specified amount of time steps. When you run the next cell, 2000 time steps are executed and the velocity field is plotted. You can run the cell multiple times to see a time evolution.
 %% Cell type:code id: tags:
 ``` python
 ldc_scenario.run(2000)
 plt.figure(dpi=200)
 plt.vector_field(ldc_scenario.velocity_slice(), step=2);
 ```
 %% Output
 %% Cell type:markdown id: tags:
 ### Variations to experiment with:
 - simulate with a higher ``relaxation_rate`` (i.e. higher [Reynolds number](https://en.wikipedia.org/wiki/Reynolds_number)), keep in mind that the ``relaxation_rate`` has to be smaller than 2. You might have to increase (``domain_size``) to keep the simulation stable and run more time steps to get to the stationary solution. You also might want to increase the ``step`` parameter for the plot, to reduce the number of arrows.
 - run a 3D simulation by adding a third dimension size to ``domain_size``. The ``velocity`` property of the scenario is now a 3D field that has to be sliced before it can be plotted, e.g. ``ldc_scenario.velocity[:, :, 10, 0:2]`` generates a slice at ``z=10`` and plot the ``x`` and ``y`` component of the velocity.
 %% Cell type:markdown id: tags:
 ##  Fully periodic flow
 Another simple scenario is a box with periodic boundary conditions in all directions. We initialize a non-zero initial velocity field, which is decaying over time due to viscous effects and the absence of driving forces or boundary conditions. In this example we initialize a shear flow where in one stripe the fluid is moving to the left, and everywhere else to the right. We perturbe this initial velocity field with random noise to get an instable shear layer.
 %% Cell type:code id: tags:
 ``` python
 width, height = 200, 60
 velocity_magnitude = 0.05
 init_vel = np.zeros((width,height,2))
 # fluid moving to the right everywhere...
 init_vel[:, :, 0] = velocity_magnitude
  # ...except at a stripe in the middle, where it moves left
 init_vel[:, height//3 : height//3*2, 0] = -velocity_magnitude
 # small random y velocity component
 init_vel[:, :, 1] = 0.1 * velocity_magnitude * np.random.rand(width,height)
 plt.figure(dpi=200)
 plt.vector_field(init_vel, step=4);
 ```
 %% Output
 %% Cell type:markdown id: tags:
 With this initial velocity field we create a simulation scenario:
 %% Cell type:code id: tags:
 ``` python
 shear_flow_scenario = create_fully_periodic_flow(initial_velocity=init_vel, relaxation_rate=1.97)
 ```
 %% Cell type:code id: tags:
 ``` python
 shear_flow_scenario.run(500)
 plt.figure(dpi=200)
 plt.vector_field(shear_flow_scenario.velocity[:, :])
 ```
 %% Output
     <matplotlib.quiver.Quiver at 0x7fe7a80e2bb0>
 %% Cell type:markdown id: tags:
 Instead of plotting a single point in time we create an animation. For this we first have to
 define an update function that runs a few time steps and returns the field to plot.
 This function is called ``iterations`` times, then the animation stops.
 To cancel the animation while it is running, hit the stop button in the IPython menu bar.
 %% Cell type:code id: tags:
 ``` python
 # def next_frame():
 #     shear_flow_scenario.run(50)
 #     return shear_flow_scenario.velocity[:, :]
 # plt.figure(dpi=200)
 # display_animation(plt.vector_field_animation(next_frame, step=2), iterations=50)
 ```
 %% Cell type:markdown id: tags:
 Vortices are created between the two layers. This phenomenon is called [Kelvin-Helmholz Instability](https://en.wikipedia.org/wiki/Kelvin%E2%80%93Helmholtz_instability). For a better visualization of the vortices we can plot the [vorticity](https://en.wikipedia.org/wiki/Vorticity) of velocity field:
 %% Cell type:code id: tags:
 ``` python
 plt.figure(dpi=200)
 plt.scalar_field(vorticity_2d(shear_flow_scenario.velocity[:, :]));
 ```
 %% Output
 %% Cell type:markdown id: tags:
 ###  Variations to experiment with:
 - make an animation of the vorticity
 - increase the ``relaxation_rate``. What is the maximum relaxation rate you can get before the simulation gets unstable?
 - use an entropic method to get to higher relaxation rates:
 ```
 entropic_shear_flow_scenario = create_fully_periodic_flow(initial_velocity=init_vel, method='trt-kbc-n4',
                                                           entropic=True, compressible=True)
 entropic_shear_flow_scenario.kernel_params['omega_0'] = 1.999
 ```
 %% Cell type:markdown id: tags:
 ## Channel
 In the last part of this tutorial you learn how to modify the boundary handling of scenarios.
 Therefor we set up a channel flow and place some objects into it.
 The channel will be driven by a constant body force e.g. gravity which acts in x direction. Along the flow direction periodic boundary conditions are used whereas the walls are modeled with a *noslip* boundary condition.
 %% Cell type:code id: tags:
 ``` python
 channel_scenario = create_channel(domain_size=(300, 100), force=1e-7, initial_velocity=(0.025, 0),
                                   relaxation_rate=1.97,
                                   config=CreateKernelConfig(target=Target.GPU))
 ```
 %% Cell type:code id: tags:
 ``` python
 channel_scenario._lbmKernels[0].ast
 ```
 %% Output
     KernelFunction kernel([_data_force_driven_channel_pdfSrc, _data_force_driven_channel_pdfTmp])
 %% Cell type:markdown id: tags:
 As in the last scenario, we specify an initial velocity here. Instead of passing a velocity value for every cell we specify here a constant for the complete domain.
 %% Cell type:code id: tags:
 ``` python
 channel_scenario.run(10000)
 plt.figure(dpi=200)
 plt.vector_field(channel_scenario.velocity[:, :], step=4);
 ```
 %% Output
 %% Cell type:markdown id: tags:
 This is a 2D [Poiseuille flow](https://en.wikipedia.org/wiki/Hagen%E2%80%93Poiseuille_equation) where a parabolic profile of the x velocity is expected for the stationary case.
 %% Cell type:code id: tags:
 ``` python
 vel_profile = channel_scenario.velocity[0.5, :, 0]
 plt.figure(dpi=200)
 plt.plot(vel_profile);
 ```
 %% Output
 %% Cell type:markdown id: tags:
 The stationary state is not yet reached, you can run more time steps and see how the profile gets closer to a parabola.
 ### Modifying boundaries
 Lets first view the current boundary configuration:
 %% Cell type:code id: tags:
 ``` python
 def draw_boundary_setup():
     fig = plt.figure(figsize=(10.0, 3.0), dpi=200)
     plt.boundary_handling(channel_scenario.boundary_handling)
     plt.axis('off');
 draw_boundary_setup()
 ```
 %% Output
 %% Cell type:markdown id: tags:
 In above plot you can see that the *no-slip* boundaries at the top and bottom of the channel, otherwise the channel is empty.
 Since an empty channel is pretty boring, lets put an obstacle in it. We start with the simplest option: a rectangular, solid block. The rectangle is specified as a slice, similar to advanced *numpy* indexing. The ``make_slice`` function can also take ``float`` as indices for specifying the slice relative to the domain size. The following cell puts an obstacle into the domain that has one third of the channel height.
 Additionally we have to pass a function that defines what should happen at the boundary (here ``noSlip``).
 By default, the name of the function is also the boundary name.
 %% Cell type:code id: tags:
 ``` python
 from lbmpy.boundaries import NoSlip
 wall = NoSlip()
 channel_scenario.boundary_handling.set_boundary(wall, make_slice[0.2:0.25, 0:0.333])
 ```
 %% Output
     2
 %% Cell type:markdown id: tags:
 When plotting the boundary handling again, we see the rectangular obstacle:
 %% Cell type:code id: tags:
 ``` python
 draw_boundary_setup()
 ```
 %% Output
 %% Cell type:markdown id: tags:
 When setting and plotting boundaries the domain is actually 2 cells larger than originally specified. These so called 'ghost layer' slices are one cell thick and are automatically added at each domain boundary. They can be used to set boundaries and are also used for communication when running distributed memory parallel simulations.
 When specifying the slice, keep in mind that the domain is actually slightly larger. When plotting the simulation results the ghost layers are automatically removed.
 To convert a cell back to ``domain``, the same method can be used. To demonstrate this, we cut a piece out of the obstacle:
 %% Cell type:code id: tags:
 ``` python
 channel_scenario.boundary_handling.set_boundary('domain', make_slice[0.2:0.235, 0.0333:0.3])
 fig = plt.figure(figsize=(10.0, 3.0), dpi=200)
 plt.boundary_handling(channel_scenario.boundary_handling)
 plt.axis('off');
 ```
 %% Output
 %% Cell type:markdown id: tags:
 To add non-rectangular obstacles one can also pass a mask array, which is ``True`` for cells where the boundary should be set. This is demonstrated in the next cell, where a sphere is placed in the channel.
 %% Cell type:code id: tags:
 ``` python
 def set_sphere(x, y):
     shape = channel_scenario.domain_size
     mid = (0.5 * shape[0], 0.5 * shape[1])
     radius = 13
     return (x-mid[0])**2 + (y-mid[1])**2 < radius**2
 channel_scenario.boundary_handling.set_boundary(wall, mask_callback=set_sphere)
 draw_boundary_setup()
 ```
 %% Output
 %% Cell type:markdown id: tags:
 Now, we run the simulation to see the flow aroung the obstacles:
 %% Cell type:code id: tags:
 ``` python
 channel_scenario.run(10000)
 plt.figure(dpi=200)
 plt.vector_field_magnitude(channel_scenario.velocity[:,:]);
 ```
 %% Output
 %% Cell type:markdown id: tags:
 ###  Variations to experiment with:
 - increase the Reynolds number. You might also have to increase the resolution, and/or use a more advanced method like cumulant or entropic stabilization

doc/notebooks/04_tutorial_cumulant_LBM.ipynb

@@ -673,7 +673,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -687,7 +687,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.2"
+   "version": "3.11.4"
   },
   "vscode": {
    "interpreter": {