Documentation for Analyzing Particle Simulation Output Using HDF5

This section provides a step-by-step guide on how to analyze and visualize the output data from a particle simulation using HDF5 files. We will demonstrate how to load the results, process the data, and plot the variation of a specific quantity (in this case, the position of a particle) over time using Python libraries such as h5py and matplotlib.

Simulation Overview

As an example, we consider the hdf5 output example of Cabana. In our simulation, we have 9 particles initially placed at equal distances from each other. Each particle starts with a unit velocity along the x-axis. The simulation runs for a total of 1 second, with a time step of 0.01 seconds. Data is output at intervals of 10 timesteps, generating a total of 10 HDF5 files. The filenames are of the format particles_XX.h5, where XX is the output step number.

Prerequisites

To follow this guide, you need the following:

Python 3.10 or higher
h5py library for handling HDF5 files
matplotlib library for plotting
Simulation output files in HDF5 format

You can install the required libraries using pip:

pip install h5py matplotlib

Running the Simulation

To run the simulation, use the following commands in your terminal:

=> cd /home/user/Cabana/build
=> ./example/core_tutorial/13_hdf5_output/HDF5Output

During execution, the program will generate output files and provide console output as shown below:

Kokkos::OpenMP::initialize WARNING: OMP_PROC_BIND environment variable not set
  In general, for best performance with OpenMP 4.0 or better set OMP_PROC_BIND=spread and OMP_PLACES=threads
  For best performance with OpenMP 3.1 set OMP_PROC_BIND=true
  For unit testing set OMP_PROC_BIND=false

Cabana HDF5 output example

Output for step 0/100
Output for step 10/100
Output for step 20/100
Output for step 30/100
Output for step 40/100
Output for step 50/100
Output for step 60/100
Output for step 70/100
Output for step 80/100
Output for step 90/100

This process will produce a series of HDF5 and XMF files representing the simulation state at each output step.

Accessing the Output Data

The simulation produces files named particles_XX.h5 and particles_XX.xmf, where XX is the step number. Our objective is to analyze the position data of the first particle (with index 0) over time.

Step 1: Set Up the Environment

We will use ipython to run the analysis interactively. Launch ipython from your terminal:

=> ipython

Load the required packages:

import h5py
import matplotlib.pyplot as plt
import os

Step 2: Locate and Sort the Output Files

We need to locate the output files and sort them in ascending order based on the timestep:

directory_name = "./"
files = [filename for filename in os.listdir(directory_name)
         if filename.startswith("particles") and filename.endswith("h5")]
files.sort()

files_num = []
for f in files:
    f_last = f[10:]  # Extract the step number from the filename
    files_num.append(int(f_last[:-3]))  # Remove the ".h5" extension
files_num.sort()

sorted_files = []
for num in files_num:
    sorted_files.append(f"particles_{num}.h5")

files = sorted_files

Step 3: Extract and Plot the Position Data

We loop through each file, extract the position data of the first particle, and plot it against time:

position = []
time = []

for f in files:
    with h5py.File(directory_name + f, "r") as file:
        position.append(file["positions"][0][0])  # Access the x-position of the first particle
        time.append(file.attrs["Time"])  # Extract the simulation time from attributes

plt.plot(time, position, label="Position")
plt.xlabel("Time (s)")
plt.ylabel("Position (m)")
plt.title("Variation of Particle Position Over Time")
plt.legend()
plt.grid(True)
plt.show()

Explanation of the Code:

File Handling: We use h5py to open each HDF5 file and extract the position data for the first particle. The with statement ensures that each file is properly closed after use.
Data Extraction: The position is stored in the dataset positions, where we select the first particle's x-position (index [0][0]). The simulation time is accessed from the file's attributes.
Plotting: We use matplotlib to create a line plot of the particle's position over time. The plot is customized with labels, a title, a legend, and a grid for better readability.

Conclusion

This document provides a complete workflow for analyzing simulation data stored in HDF5 files. By following these steps, you can visualize how specific quantities, such as the position of a particle, vary over time in your simulations. You can extend this approach to analyze and visualize other types of data as needed.

dineshadepu/Cabana_post_processing.md