diff --git a/README.md b/README.md index d92c36b6..705d90f2 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ The following two folders from this repository allow to run the experiments and Both folders contain subfolders corresponding to the following subsections of the results section of Rodenberg [^Rodenberg2025]: -* `oscillator-overlap`: 4.1 Oscillator problem +* `oscillator-overlap`: 4.1 Partitioned oscillator * `partitioned-heat-conduction`: 4.2 Partitioned heat conduction * `perpendicular-flap`: 4.3 Perpendicular flap @@ -19,13 +19,11 @@ If you want to run the experiments from the paper, please refer to `experiments/ ## Running the experiments and creating the plots with GitHub Actions -The following folders contain job definitions and Dockerfiles that allow to run the experiments and create the plots using GitHub Actions. +The following folders contain job definitions and Dockerfiles that allow to run the experiments and create the plots using GitHub Actions. You can ignore these folders if you want to run the experiments locally. * `.github/workflows`: Definition of pipelines that allow to perform the experiments using [GitHub Actions](https://github.com/features/actions). You can fork this repository to run the experiments and create the plots with GitHub Actions. Alternatively, you can also find the artifacts created by the GitHub Actions pipeline on the branch [`gh-pages`](https://github.com/BenjaminRodenberg/test-cases-dissertation/tree/gh-pages). * `tools/docker`: Docker files used by the CI job `.github/workflows/publish-docker.yml` to create docker images for running the experiments. The docker images can be found under https://hub.docker.com/r/benjaminrodenberg/fenics-openfoam and https://hub.docker.com/r/benjaminrodenberg/precice-openfoam. -You can ignore these folders if you want to run the experiments locally. However, you can also [fork this repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) with your GitHub account and run a CI pipeline to perform the experiments and create the plots using GitHub CI runners. - [^RodenbergUekermann2025]: Rodenberg, Benjamin; Uekermann, Benjamin. *A waveform iteration implementation for black-box multi-rate higher-order coupling*. [Manuscript in preparation] [^Chen2024]: Chen, Jun; Chourdakis, Gerasimos; Desai, Ishaan; Homs-Pons, Carme; Rodenberg, Benjamin; Schneider, David; Simonis, Frédéric; Uekermann, Benjamin; Davis, Kyle; Jaust, Alexander; Kelm, Mathis; Kotarsky, Niklas; Kschidock, Helena; Mishra, Durganshu; Mühlhäußer, Markus; Schrader, Timo Pierre; Schulte, Miriam; Seitz, Valentin; Signorelli, Joseph; van Zwieten, Gertjan; Vinnitchenko, Niklas; Vladimirova, Tina; Willeke, Leonard; Zonta, Elia. *preCICE Distribution Version v2404.0*. DaRUS, 2024, V1. https://doi.org/10.18419/darus-4167. [^Rodenberg2025]: Rodenberg, Benjamin. *Flexible and robust time stepping for partitioned multiphysics*. Technical University of Munich, 2025. https://nbn-resolving.org/urn:nbn:de:bvb:91-diss-20250424-1763172-0-4 diff --git a/experiments/README.md b/experiments/README.md index 7aa655de..7e3c359d 100644 --- a/experiments/README.md +++ b/experiments/README.md @@ -4,32 +4,29 @@ This folder `experiments` contains the scenarios and all required data and helpe ## Overview -The subfolders of this folder refer to the test cases provided in Section 4 Results and follow the naming convention of the three test cases at the root level of this repository: +The subfolders of this folder refer to the test cases provided in *Section 4 Results*: * `experiments/oscillator-overlap` corresponds to *Section 4.1 Partitioned oscillator* * `experiments/partitioned-heat-conduction` corresponds to *Section 4.2 Partitioned heat conduction* * `experiments/perpendicular-flap` corresponds to *Section 4.3 Perpendicular flap* -In the following sections of this document provide installation instructions for the necessary dependencies for running the cases and instructions on how to run the individual cases. The cases closely follow the tutorial cases from the preCICE distribution version v2404.0 [^Chen2024]. Please refer to the tutorial descriptions on [the preCICE website](https://precice.org/tutorials.html) or to the `README.md` files of the respective cases under [github.com/precice/tutorials](github.com/precice/tutorials) for details on the setups ([v2024.04](https://github.com/precice/tutorials/tree/v202404.0)). +The following sections of this README document provide installation instructions for necessary dependencies and instructions on how to run the cases. The cases closely follow the [tutorial cases from the preCICE distribution version v2404.0](https://github.com/precice/tutorials/tree/v202404.0) [^Chen2024]. Refer to the tutorial descriptions on [the preCICE website](https://precice.org/tutorials.html) for details on the setups. ## Dependencies & installation steps -You can start from a recent Linux-based system (Ubuntu 24.04 is recommended). Alternatively, the preCICE distribution version v2404.0 [^Chen2024] should provide a good basis for running the experiments provided in this repository. - -In contrast to the preCICE distribution version v2404.0 a more recent version of preCICE and of some adapters will be required and have to be installed. The experiments are known to run as expected on a system with the following specification: +You can start from a recent Linux-based system (Ubuntu 24.04 is recommended). The experiments are known to run on a system with the following specification: ### preCICE components * preCICE [`3.2.0`](https://github.com/precice/precice/releases/tag/v3.2.0) -* pyprecice [`3.2.1`](https://github.com/precice/python-bindings/releases/tag/v3.2.1) (automatically installed via `requirements.txt` of the respective case) -* FEniCS adapter [`2.2.0`](https://github.com/precice/fenics-adapter/releases/tag/v2.2.0) (automatically installed via `requirements.txt` of the respective case) +* pyprecice [`3.2.1`](https://github.com/precice/python-bindings/releases/tag/v3.2.1) (automatically installed via `requirements.txt` of the respective cases) +* FEniCS adapter [`2.2.0`](https://github.com/precice/fenics-adapter/releases/tag/v2.2.0) (automatically installed via `requirements.txt` of the respective cases) * OpenFOAM adapter [`1.3.1`](https://github.com/precice/openfoam-adapter/releases/tag/v1.3.1) -### OS and other dependencies +### Other dependencies -* Recommended OS: Ubuntu `24.04`, but the workflow should work similarly for other Ubuntu versions or Linux-based systems -* The Python package [prepesthel](https://pypi.org/project/prepesthel/) for automation of preCICE runs (automatically installed via `requirements.txt` of the respective case) -* Additional python packages (automatically installed via `requirements.txt` of the respective case) +* The Python package [prepesthel](https://pypi.org/project/prepesthel/) for automation of preCICE runs (automatically installed via `requirements.txt` of the respective cases) +* Additional python packages (automatically installed via `requirements.txt` of the respective cases) * FEniCS `2019.2.0.64.dev0` (installed from FEniCS PPA https://launchpad.net/~fenics-packages/+archive/ubuntu/fenics; compare version provided by `python3 -c "import dolfin;print(dolfin.__version__)"` or run `fenics-version`) * OpenFOAM `2412` from OpenCFD / ESI (openfoam.com) @@ -37,14 +34,14 @@ In contrast to the preCICE distribution version v2404.0 a more recent version of The following steps will install the required dependencies: -1. **preCICE**: Download the Debian package (`.deb`) of preCICE 3.2.0 from [here](https://github.com/precice/precice/releases/tag/v3.2.0) and install it on your system by running the command +1. **preCICE**: Download the Debian package (`.deb`) of [preCICE v3.2.0](https://github.com/precice/precice/releases/tag/v3.2.0) and install it on your system by running the command ```sh wget https://github.com/precice/precice/releases/download/v3.2.0/libprecice3_3.2.0_noble.deb sudo apt install -y libprecice3_3.2.0_noble.deb ``` - Note: The code name `noble` refers to Ubuntu 24.04, see [here](https://documentation.ubuntu.com/project/release-team/list-of-releases/). If you are using a different Ubuntu version, please replace `noble` with the respective code name. + Note: The code name `noble` refers to Ubuntu 24.04, see [Ubuntu docs](https://documentation.ubuntu.com/project/release-team/list-of-releases/). If you are using a different Ubuntu version, please replace `noble` with the respective code name. 2. **FEniCS**: Enter the following commands: @@ -55,7 +52,7 @@ The following steps will install the required dependencies: sudo apt install -y fenics ``` - These installation instructions similar to the instructions from [here](https://fenicsproject.org/download/archive/). + These installation instructions are similar to the instructions the [FEniCS docs](https://fenicsproject.org/download/archive/). 3. **OpenFOAM 2414**: Enter the following commands: @@ -65,7 +62,7 @@ The following steps will install the required dependencies: sudo apt install -y openfoam2412-default ``` - These installation instructions are similar to the instructions from [here](https://develop.openfoam.com/Development/openfoam/-/wikis/precompiled/debian). After that, you also need to source the OpenFOAM bashrc file: + These installation instructions are similar to the instructions from the [OpenFOAM docs](https://develop.openfoam.com/Development/openfoam/-/wikis/precompiled/debian). After that, you also need to source the OpenFOAM bashrc file: ```sh source /usr/lib/openfoam/openfoam2412/etc/bashrc @@ -86,25 +83,25 @@ The following steps will install the required dependencies: ./Allwmake ``` -5. **pyprecice, the FEniCS adapter, and other Python dependencies**: These dependencies will be fetched automatically from PyPI and installed into an individual virtual environment for each case for setting up the virtual environment, please execute the following commands: +5. **pyprecice, the FEniCS adapter, and other Python dependencies**: These dependencies are fetched automatically from PyPI and installed into an individual virtual environment for each case. For example: ```sh cd oscillator-overlap ./make-venv.sh ``` - The command above will create a virtual environment with all the required Python dependencies in the folder `.venv` in `oscillator-overlap`. You can easily get a list of the installed Python packages by running `.venv/bin/pip freeze` from `oscillator-overlap` and you should see `pyprecice` and `prepesthel` in this list. If you want to run one of the other cases please replace `oscillator-overlap` with `partitioned-heat-conduction` or `perpendicular-flap` above. + The command above creates a virtual environment with all required Python dependencies in the folder `.venv` in `oscillator-overlap`. You can get a list of the installed Python packages by running `.venv/bin/pip freeze`. ## Running the test cases -Each case is represented by a subfolder `oscillator-overlap`, `partitioned-heat-conduction`, and `perpendicular-flap`. They are forked from the preCICE tutorials from [github.com/precice/tutorials](github.com/precice/tutorials) and follow their basic structure. Additionally, they contain some helper scripts needed for setting up the runtime environment, running the experiments, and postprocessing data for plotting: +The test cases are forked from the [preCICE tutorials](https://github.com/precice/tutorials) and follow their basic structure. Additionally, they contain helper scripts for setting up the runtime environment, running the experiments, and postprocessing data for plotting: -* The script `make-venv.sh` allows to create a virtual environment needed for running the experiments (see above for usage). -* A helper script `run_experiments.sh` that will automatically run all experiments required for each study (convergence study, comparison of iteration numbers etc.). It is recommended to navigate to the respective folder and run this script. This should automatically execute all experiments. -* A folder `configs` with `.csv` files defining configurations (e.g., time window sizes or time step sizes) for individual experiments. -* A folder `results`. After running the experiments this folder will contain all the relevant data for creation of the plots. -* Python scripts `doConvergenceStudy.py`, respectively `doConvergenceStudyMonolithic.py` required for automation of experiment runs via the Python package [prepesthel](https://pypi.org/project/prepesthel/). -* In contrast to the original preCICE tutorials there is no `precice-config.xml` but a `precice-config.xml.jinja2` Jinja2 template. This template will be processed by the Jinja2 engine to create preCICE configuration files for the respective experiments. +* `make-venv.sh` creates a virtual environment needed for running the experiments (see above). +* `run_experiments.sh` runs all experiments required for each study (convergence study, comparison of iteration numbers etc.). It is recommended to navigate to the respective folder and run this script. +* Folder `configs` with `.csv` files defines configurations (e.g., time window sizes or time step sizes) for individual experiments. +* Folder `results` will contain all relevant data for creation of the plots after running the experiments. +* Python scripts `doConvergenceStudy.py` and `doConvergenceStudyMonolithic.py` are indirectly called by `run_experiments.sh` and use the Python package [prepesthel](https://pypi.org/project/prepesthel/) to execute multiple preCICE experiments and create reports with their results. +* In contrast to the original preCICE tutorials, there is no `precice-config.xml`, but a `precice-config.xml.jinja2` Jinja2 template. This template is processed by the Jinja2 engine to create preCICE configuration files for the respective experiments. ### Example: Run experiments from Section 4.1 @@ -115,8 +112,6 @@ cd oscillator-overlap ./run_experiments.sh ``` -For other experiments, simply replace `oscillator-overlap` with `partitioned-heat-conduction` or `perpendicular-flap`. - After running the experiments, you will find all data in the `results` folder. For `oscillator-overlap` this looks as follows: ``` @@ -163,6 +158,6 @@ results/ └── rQN.csv ``` -You can copy this data to the respective location in the `plotting` folder at the root of this repository or use precomputed data already present at this location. +You can copy this data to the respective location in the `plotting` folder at the root of this repository or instead use the precomputed data already there. [^Chen2024]: Chen, Jun; Chourdakis, Gerasimos; Desai, Ishaan; Homs-Pons, Carme; Rodenberg, Benjamin; Schneider, David; Simonis, Frédéric; Uekermann, Benjamin; Davis, Kyle; Jaust, Alexander; Kelm, Mathis; Kotarsky, Niklas; Kschidock, Helena; Mishra, Durganshu; Mühlhäußer, Markus; Schrader, Timo Pierre; Schulte, Miriam; Seitz, Valentin; Signorelli, Joseph; van Zwieten, Gertjan; Vinnitchenko, Niklas; Vladimirova, Tina; Willeke, Leonard; Zonta, Elia. *preCICE Distribution Version v2404.0*. DaRUS, 2024, V1. https://doi.org/10.18419/darus-4167. diff --git a/plotting/README.md b/plotting/README.md index 25e18b89..182535a4 100644 --- a/plotting/README.md +++ b/plotting/README.md @@ -4,7 +4,7 @@ This folder `plotting` contains the LaTeX sources and auxiliary scripts to creat ## Overview -The subfolders refer to the test cases provided in *Section 4* Results and follow the naming convention of the three test cases at the root level of this repository: +The subfolders refer to the test cases provided in *Section 4 Results*: * `plotting/oscillator-overlap` corresponds to *Section 4.1 Partitioned oscillator* * `plotting/partitioned-heat-conduction` corresponds to *Section 4.2 Partitioned heat conduction* @@ -12,48 +12,46 @@ The subfolders refer to the test cases provided in *Section 4* Results and follo Additionally, there are the following files for automation of the plotting: -* A `Dockerfile` to setup the runtime environment in Docker (see below) -* A `requirements.txt` to define the Python dependencies needed for plotting -* A `Makefile` that allows to automatically perform preprocessing steps and create the plots for all cases +* `Dockerfile` to setup the runtime environment in Docker (see below) +* `requirements.txt` to define the Python dependencies needed for plotting +* `Makefile` to automatically perform preprocessing steps and create the plots for all cases The subfolders corresponding to the test cases contain subfolders named `FigX` or `TabX` for the respective figures and tables from *Section 4 Results*. These folders contain: * `*.tex` files with the LaTeX sources or (for more complex plots) `*.tex.jinja2` templates that will be filled with data using a Python script and Jinja2 to create a `*.tex` file in a preprocessing step. -* `data` folder with the results produced by the respective test case. For convenience the data is already provided here. If you want to compute this data on your own, please refer to the `experiments/README.md`. -* A `Makefile` to create PDF files with the respective figures or tables. +* `data` folder with the results produced by the respective test case. For convenience, the data is already provided. If you want to compute the data on your own, please refer to `experiments/README.md`. +* `Makefile` to create PDF files with the respective figures or tables. ## Prerequisites -For creating the figures and tables you need a working LaTeX installation and Python with the packages `scipy`, `pandas`, `jinja2`, and `matplotlib`. It is recommended to use Ubuntu 24.04. But the workflow should be similar for other Ubuntu versions or Linux-based systems. +For creating the figures and tables you need a working LaTeX installation and Python with the packages `scipy`, `pandas`, `jinja2`, and `matplotlib`. It is recommended to use Ubuntu 24.04. -### Use docker +### Using docker -The `Dockerfile` in this folder allows you to create a docker container with all the required dependencies. Please install Docker on your operating system by following the instructions given on https://docs.docker.com/engine/install/. +The `Dockerfile` allows creating a container with all required dependencies. [Install Docker on your system](https://docs.docker.com/engine/install/). -You can then build the docker container by running the following command from this folder: +You can then build the Docker container: ```sh docker build -t waveform-plotting . ``` -You can also use a name of your choice instead of `waveform-plotting`. - ### Use your own system -You need a working LaTeX installation and some Python packages on your system. Please install all required packages by running +Install LaTex and Python: ```sh sudo apt install -y texlive-full sudo apt install -y python3 python3-pip ``` -Please install additional Python packages either via your package manager by running +Install additional Python packages either via your package manager: ```sh sudo apt install -y python3-pygments python3-pandas python3-scipy python3-jinja2 ``` -alternatively, you can use a virtual environment. This will require installing `python3-venv` and then the packages given in the `requirements.txt` from this folder: +Or using a virtual environment. This requires installing `python3-venv` and then the packages given in the `requirements.txt`: ```sh sudo apt install -y python3-venv @@ -62,13 +60,13 @@ source .venv/bin/activate pip3 install -r requirements.txt ``` -This will create a virtual environment `.venv`. Please ensure that this virtual environment is active when trying to create the figures and table as described below +This creates a virtual environment `.venv`. Activate with `source .venv/bin/activate`. ## Creating the figures and tables -If you installed the prerequesites as described above on your own system please run `make` from this folder to create all figures and tables. To create individual figures and tables, please navigate to the respective folder and run `make` there. +If you installed the prerequesites on your own system, run `make` to create all figures and tables. To directly create individual figures and tables, navigate to the respective folder and run `make` there. -If you are using docker, instead of running `make` use the following command to run the `make` command in the docker container and write the output back to your file system: +If you are using Docker, run `make` in the container and directly write output back to your system: ```sh docker run --rm -v "$PWD":/doc -w /doc waveform-plotting make @@ -78,22 +76,11 @@ This procedure also works for individual figures and tables if you run it from t ### Example: Create Figure 11 -If you, for example, only want to create Figure 11, please navigate to the respective folder and execute `make`: - -```sh -cd oscillator-overlap/Fig11 -make -``` - -This should create the file `main.pdf` with Figure 11 using the precomputed data from `plotting/oscillator-overlap/Fig11/data`. - -If you want to start from scratch and use data that you computed on your own system, please delete the folder `plotting/oscillator-overlap/Fig11/data` and copy the data from `experiments/oscillator-overlap/results/Fig11/data` to the correct location (see `experiments/README.md` for instructions how to create this data): +If you only want to create Figure 11, navigate to the respective folder and execute `make`: ```sh -rm -r oscillator-overlap/Fig11/data -cp -r ../experiments/oscillator-overlap/results/Fig11/data oscillator-overlap/Fig11/data cd oscillator-overlap/Fig11 make ``` -This should again result in a file `main.pdf` with Figure 11. +This creates the file `main.pdf` with Figure 11 using the precomputed data from `plotting/oscillator-overlap/Fig11/data`.