Environment Setup

During this practical session, we will use the samurai library and demonstrate its capabilities through a series of coding exercises. Please follow the instructions below to set up your development environment.

Prerequisites¶

Before starting, ensure you have the following installed on your system:

• Git (to clone the repository)

• Conda, Miniconda or Micromamba (recommended for easy setup)

• ParaView (for visualization of 2D/3D results)

If you prefer a manual setup without conda, you will also need:

• A C++ compiler supporting C++20 (e.g., GCC 10+, Clang 12+)

• CMake (version 3.16 or later)

• The following libraries: xtensor, HighFive, MPI, fmt, pugixml, cli11 (see details below)

The first step is to clone the samurai hands-on repository from GitHub. You can do this by running the following command in your terminal:

git clone https://github.com/hpc-maths/2025-hands-on-samurai.git

Go to the cloned directory:

cd 2025-hands-on-samurai

We provide a conda environment file (environment.yml) to facilitate the setup process. You can create and activate the conda environment by running the following commands in your terminal:

conda env create -f conda/environment.yml
conda activate samurai-practical-session

If you want to set up the environment manually, please ensure you have the following dependencies installed:

Verifying the setup¶

To verify that your environment is set up correctly, you can compile and run the provided example code. Navigate to the practical_session/material/00-setup directory and execute the following commands:

cd practical_session/material/00-setup
cmake -S . -B build
cmake --build build
./build/samurai_setup_test -h

Expected output: You should see a help message listing the available command-line options for the test program. If you see this, your samurai installation is working correctly!

If you encounter any issues during the setup process, please refer to the samurai documentation or reach out to the course instructors for assistance.

Verify the visualization tools¶

For Multi-Dimensional Simulations (2D/3D)¶

To visualize results from 2D or 3D simulations, you will need ParaView. Download it from the official ParaView website if not already installed.

Testing ParaView visualization:

1. Open ParaView

2. File → Open → Navigate to practical_session/material/00-setup/outputs/2d_example.xdmf

3. Select the XDMF Reader in the list

4. Click Apply in the Properties panel

5. You should see a 2D field visualization

For 1D simulations¶

ParaView does not support 1D visualizations directly. Instead, use the Python script provided with samurai.

Testing 1D visualization:

Navigate to the outputs directory and run the script:

cd practical_session/material/00-setup/outputs
python read_mesh.py 1d_example --field u

Expected output: A matplotlib window should appear showing a 1D plot of the field u.

Next Steps¶

If you successfully:

• ✅ Built and ran the test program

• ✅ Visualized the 2D example in ParaView

• ✅ Visualized the 1D example with the Python script

Congratulations! 🎉 Your environment is fully set up and you’re ready to proceed with the practical sessions.

Troubleshooting: If you encountered any issues, please:

• Check the samurai documentation

• Review the error messages carefully

• Ask the course instructors for assistance

Now, proceed to First Steps to begin the practical session. Enjoy coding with samurai!