1. Organizing the source code

Please place all your sources into the src folder.

Binary files must not be uploaded to the repository (including executables).

Mesh files should not be uploaded to the repository. If applicable, upload gmsh scripts with suitable instructions to generate the meshes (and ideally a Makefile that runs those instructions). If not applicable, consider uploading the meshes to a different file sharing service, and providing a download link as part of the building and running instructions.

2. Chosing the test to run

The test case is selected in main.cpp. To run a specific test, comment out the currently active test line and uncomment the line corresponding to the test you want, then recompile and run the executable.

3. Compiling

To build the executable, make sure you have loaded the needed modules with

$ module load gcc-glibc dealii

Then run the following commands:

$ mkdir build
$ cd build
$ cmake ..
$ make

The executable will be created into build, and can be executed through

$ ./executable-name

4. Mesh Generation

The meshes were modeled and generated using Gmsh. The reference geometry is the channel flow past a cylindrical obstacle.

The repository includes a ready-to-use 2D mesh (mesh-2D.msh) and several .geo scripts to generate 3D meshes at various refinement levels.

• mesh-3D-5.geo (Ultra Coarse): Designed for rapid testing and debugging. It targets 5 nodes across the cylinder diameter (lc_cyl = 0.02), with very large cells in the rest of the domain (lc_global = 0.15).
• mesh-3D-10.geo (Coarse/Medium): A middle ground for quick runs. It targets 10 nodes across the diameter (lc_cyl = 0.01, lc_global = 0.1).
• mesh-3D-20.geo (Realistic Base): The recommended starting point for meaningful 3D simulations. It targets 20 nodes across the diameter (lc_cyl = 0.005, lc_global = 0.05), which is generally sufficient to capture the basic physics of the 3D wake.
• mesh-3D-40.geo (Highly Refined): A high-resolution mesh targeting 40 nodes across the diameter (lc_cyl = 0.0025, lc_global = 0.025), suitable for highly accurate results.

How to generate the .msh: The meshes can be generated by navigating to the directory containing the .geo files and run the command:

• For 3D meshes: Use the -3 flag.

gmsh -3 <mesh-3D-name>.geo -o <mesh-3D-name>.msh

• For 2D meshes: Use the -2 flag.

gmsh -2 <mesh-2D-name>.geo -o <mesh-2D-name>.msh

5. Cluster Execution

The solver is parallelized with MPI to run on the MOX's cluster. The cluster is equipped with a PBS/Torque job scheduler, so we use the job.pbs file.

Job Configuration: The included job.pbs requests the following baseline resources:

• Nodes and Cores: 1 node, 4 CPUs, and 4 MPI processes (#PBS -l select=1:ncpus=4:mpiprocs=4).
• Walltime: An estimated maximum execution time of 4 hours (#PBS -l walltime=04:00:00).

The job will automatically navigate to the build folder of your workspace and execute the program via mpirun.

How to submit the job: Once you have compiled the code in your build directory, you can queue your simulation using the following command:

qsub job.pbs

Monitoring and Output: During execution, the cluster scheduler will redirect its logs to job_output.log and job_error.log. Additionally, the real-time output of the Navier-Stokes solver (including computation times, drag, lift, and pressure differences at each time-step) will be saved in live_output.log, with any runtime errors going to live_error.log. This allows to monitor the simulation's progress by simply checking the last few lines of the file:

tail -f build/live_output.log