diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt index 59c36c295de0103a5eb5657faee2ff1dfadc1fb4..2325a59a150872cd039792735b23a8df59c7a71e 100644 --- a/examples/CMakeLists.txt +++ b/examples/CMakeLists.txt @@ -14,4 +14,4 @@ FetchContent_MakeAvailable(walberla) add_subdirectory(${CMAKE_SOURCE_DIR}/.. ${CMAKE_BINARY_DIR}/sfg-walberla) add_subdirectory( GeneratorScriptBasics ) -add_subdirectory( ForceDrivenChannel ) +add_subdirectory( FullyPeriodicAde ) diff --git a/examples/EnvSetup/CMakeLists.txt b/examples/CMakeSetup/CMakeLists.txt similarity index 100% rename from examples/EnvSetup/CMakeLists.txt rename to examples/CMakeSetup/CMakeLists.txt diff --git a/examples/CMakeSetup/CMakeSetup.md b/examples/CMakeSetup/CMakeSetup.md new file mode 100644 index 0000000000000000000000000000000000000000..003caad5711019cd0dc3a55a6f45a5667c750a2c --- /dev/null +++ b/examples/CMakeSetup/CMakeSetup.md @@ -0,0 +1,73 @@ +(EnvSetup)= +# CMake Project Setup + +This chapter describes the necessary steps to set up a CMake project to use waLBerla +with the nextcodegen features provided by sfg-walberla. + +## Prequesites + +You are going to need at least +- a C++ compiler supporting at least C++17; +- a Python installation of version >= 3.10; +- a CMake installation of version >= 3.24; +- an up-to-date installation of Git. + +Also, the following optional dependencies are highly recommended: +- clang-format for prettier code generator output + +If you are starting from scratch, create a new, empty directory for your CMake project. +Then, set up its `CMakeLists.txt` with the following minimal settings: + +:::{literalinclude} CMakeLists.txt +:lines: 1-2 +::: + +On the other hand. if you already have a CMake project set up, you can just as well extend it. + +## Add sfg-walberla to your CMake Project + +There are many ways to include `waLBerla` and `sfg-walberla` into your project: +you can clone them locally and use `add_subdirectory`, add them as submodules, et cetera. +For getting started, though, the easiest way is to use [FetchContent][FetchContent] to dynamically +pull their sources into your build tree. + +Place the following code in your `CMakeLists.txt`: + +::::{card} {download}`CMakeLists.txt` +:::{literalinclude} CMakeLists.txt +:lines: 4- +::: +:::: + +Now, you can run `cmake` to configure your build system: + +```bash +mkdir build +cmake -S . -B build -DPython_EXECUTABLE=`pwd`/.venv/bin/python +``` + +If, near the end of the long configuration log, you see two messages like this: + +``` +-- Found pystencils Source File Generator (Version 0.1a4+25.g9d3e553) +-- Using Python interpreter <your-project-dir>/build/_deps/sfg-walberla-build/codegen-venv/bin/python for SFG generator scripts. +``` + +Then your build system setup was successful! +Now you can get down to business and populate your project with simulation applications. + +(adding_examples)= +## Adding Examples from this Manual + +As you explore the examples in this book, +you can try out each by downloading, extracting, and including them into your project. +For example, to include the [force-driven poiseulle channel example](#ForceDrivenChannel), +extract its code into the `ForceDrivenChannel` subdirectory and add + +```CMake +add_subdirectory( ForceDrivenChannel ) +``` + +to your root `CMakeLists.txt`. + +[FetchContent]: https://cmake.org/cmake/help/latest/module/FetchContent.html diff --git a/examples/EnvSetup/EnvSetup.md b/examples/EnvSetup/EnvSetup.md deleted file mode 100644 index c42f46a1726387caacb77dcef2fd8d117563e169..0000000000000000000000000000000000000000 --- a/examples/EnvSetup/EnvSetup.md +++ /dev/null @@ -1,101 +0,0 @@ -(EnvSetup)= -# Environment and Project Setup - -This chapter attempts to briefly explain the necessary steps to get next-gen code generation -working with your waLBerla-based project. -This involves two steps: - - Set up a Python environment with the required pycodegen packages; - - Set up a CMake build system including the latest versions of *walberla* and *sfg-walberla*. - -## Prequesites - -You are going to need at least -- a C++ compiler supporting at least C++17; -- a Python installation of version >= 3.10; -- a CMake installation of version >= 3.24; -- an up-to-date installation of Git. - -Also, the following optional dependencies are highly recommended: -- clang-format for prettier code generator output - -## Project Setup - -To get started, create a new, empty directory -(we are going to use `myproject` as a placeholder for your project directory). - -### Python Environment - -WaLBerla next-gen codegen relies on a set of Python packages that have not been released yet. -To simplify their installation, download our {download}`requirements.txt` file and place it in your -project directory. -Then, create and activate a new [Python virtual environment][py-venv] in your project folder: - -```bash -python -m venv .venv -source .venv/bin/activate -``` - -Next, install the required packages from the requirements file: - -```bash -export PIP_REQUIRE_VIRTUALENV=true -pip install -r requirements.txt -``` - -:::{note} -We set the `PIP_REQUIRE_VIRTUALENV` environment variable as a fail-save, -to make sure that pip rejects any attempts at installing packages -outside of a virtual environment. -::: - -Now, to see if everything worked, run the following quick-check command: - -```bash -python -c "from sfg_walberla import __version__ as v; print(f'Success! SFG-waLBerla version is {v}')" -``` - -This should print out `Success!` and the version of the code generator engine. - -### CMake - -Create a `CMakeLists.txt` file in your project directory, and populate it with at least the following code: - -::::{card} {download}`CMakeLists.txt` -:::{literalinclude} CMakeLists.txt -::: -:::: - -Here, we use [FetchContent][FetchContent] to dynamically pull both the *waLBerla* and *sfg-walberla* CMake projects. -Next, run the following commands to generate your build system: - -```bash -mkdir build -cmake -S . -B build -DPython_EXECUTABLE=`pwd`/.venv/bin/python -``` - -:::{note} -It is essential that we point CMake at the Python interpreter of the virtual environment we created above, by setting the `Python_EXECUTABLE` cache variable. -If you forget this, the CMake generation step will still run succesfully as long as your shell has that environment activated. -If it is not active, though. you might receive an error message reading: -> Could not find pystencils-sfg in current Python environment. -::: - -Done! Now we can get down to business and populate our project with waLBerla simulation applications. - -(adding_examples)= -## Adding Examples - -As you explore the examples in this book, -you can try out each by downloading and extracting them into the just-created project directory -and adding them to the CMake project. -For example, to include the [force-driven poiseulle channel example](#ForceDrivenChannel), -extract its code into the `ForceDrivenChannel` subdirectory and add - -```CMake -add_subdirectory( ForceDrivenChannel ) -``` - -to your root `CMakeLists.txt`. - -[py-venv]: https://docs.python.org/3/library/venv.html -[FetchContent]: https://cmake.org/cmake/help/latest/module/FetchContent.html diff --git a/examples/EnvSetup/requirements.txt b/examples/EnvSetup/requirements.txt deleted file mode 100644 index 62ef403ff9930f5c4ce164ce6967eac2d6e4bed5..0000000000000000000000000000000000000000 --- a/examples/EnvSetup/requirements.txt +++ /dev/null @@ -1,14 +0,0 @@ -# pystencils 2.0 Development Branch -git+https://i10git.cs.fau.de/pycodegen/pystencils.git@v2.0-dev - -# lbmpy: feature branch for pystencils-2.0 compatibility -git+https://i10git.cs.fau.de/pycodegen/lbmpy.git@fhennig/pystencils2.0-compat - -# pystencils-sfg: master -git+https://i10git.cs.fau.de/pycodegen/pystencils-sfg.git - -# sfg-walberla: master -git+https://i10git.cs.fau.de/da15siwa/sfg-walberla.git - -# for legacy waLBerla features -jinja2 diff --git a/examples/FullyPeriodicAde/AdvectionDiffusionSweep.py b/examples/FullyPeriodicAde/AdvectionDiffusionSweep.py new file mode 100644 index 0000000000000000000000000000000000000000..876da3b324faa49e13a18a589161ffe08dfb204a --- /dev/null +++ b/examples/FullyPeriodicAde/AdvectionDiffusionSweep.py @@ -0,0 +1,8 @@ +from pystencilssfg import SourceFileGenerator + +from sfg_walberla import Sweep +from sfg_walberla.symbolic import cell + + +with SourceFileGenerator() as sfg: + pass diff --git a/examples/FullyPeriodicAde/CMakeLists.txt b/examples/FullyPeriodicAde/CMakeLists.txt new file mode 100644 index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 diff --git a/examples/index.md b/examples/index.md index 6544b6e6395b65d88f4c04daa1bc84c67759b36a..618f2c81a7f9c45e877ff1aa76014b9c364daa0d 100644 --- a/examples/index.md +++ b/examples/index.md @@ -21,7 +21,7 @@ Afterward, you are free to explore the remainder of the book. :caption: Fundamentals :maxdepth: 1 -EnvSetup/EnvSetup +CMakeSetup/CMakeSetup GeneratorScriptBasics/GeneratorScriptBasics ::: diff --git a/examples/requirements.txt b/examples/requirements.txt new file mode 100644 index 0000000000000000000000000000000000000000..c353de95b9606e7e9e6fc2a65de09b763257fed3 --- /dev/null +++ b/examples/requirements.txt @@ -0,0 +1,5 @@ +sphinx +sphinx-design +myst-parser +sphinx-copybutton +sphinx-book-theme diff --git a/noxfile.py b/noxfile.py new file mode 100644 index 0000000000000000000000000000000000000000..db0fa81396f7a49a987669ba45fd75ff6db1433a --- /dev/null +++ b/noxfile.py @@ -0,0 +1,12 @@ +import nox + + +@nox.session +def user_manual(session: nox.Session): + session.chdir("examples") + session.install("-r", "requirements.txt") + + if "--clean" in session.posargs: + session.run("make", "clean", external=True) + + session.run("make", "html", external=True)