UrQMD Event Visualization Tool

This project provides a streamlined pipeline for visualizing collision events simulated in UrQMD (Ultra-relativistic Quantum Molecular Dynamics) v3.4.

Table of Contents

1. Overview
2. File Descriptions
3. Usage
4. ParaView Visualization

Overview

The pipeline consists of four primary stages:

1. File Reduction: Processes the filename.f14 output file from UrQMD, removes unnecessary whitespace, and saves it as filename_reduced.csv.
2. Data Parsing: Extracts detailed event information, calculates necessary parameters, and stores the processed data in Parquet format (default outputs/parquet).
3. Conversion to CSV: Converts the Parquet data by grouping it into time snapshots, with each snapshot saved as a separate CSV file.
4. Visualization: Uses the generated CSV files as input for the ParaView template assets/paraview/paraViewState-massVar.pvsm to visualize the events.

File Descriptions

• urqmdvis/: Core pipeline modules.
• gui.py: Desktop UI for running the pipeline and launching ParaView.
• run.py: CLI entry point for the pipeline.
• assets/paraview/paraViewState-massVar.pvsm: Default ParaView state template.
• outputs/: Default output folder (CSV/Parquet and generated ParaView states).

Usage

The primary entry point is run.py, which orchestrates the reduction, parsing, and conversion stages. To run the pipeline:

1. Install dependencies:

   • Install requirements:

     pip install -r requirements.txt

2. Run the Script:

   • Execute the following command from the terminal to initiate the pipeline:

     python run.py ../files/urqmd_AuAu_0-3fm/urqmd_1_14.dat 9 --event-name event

   • Optional flags:
     • --parquet-folder and --csv-folder to change output locations (defaults: outputs/parquet, outputs/csv).
     • --skip-reduce, --skip-parse, --skip-convert to skip steps.

3. Output:

   • The pipeline will output the CSV files into a specified folder (outputs/csv). Each CSV file contains data for an individual time slice.

Local UI Runner (CustomTkinter)

For a local desktop UI to run the full pipeline:

python gui.py

The UI lets you set the input file, event number, output folders, select which steps to run, and launch ParaView with a generated state file.

Sample Output

Here’s an example of the expected output in the terminal during the process:

Starting file reduction for: ../files/urqmd_AuAu_0-3fm/urqmd_1_14.dat
Finished processing 1702856 lines.
Reduction complete.
Output saved to: ../files/urqmd_AuAu_0-3fm/urqmd_1_14_reduced.csv
File reduction completed successfully.
Starting parsing...
Loading data from: ../files/urqmd_AuAu_0-3fm/urqmd_1_14_reduced.csv...
Data loaded successfully.
Collision Parameters:
  Total Time (tottime): 25.0
  Delta Time (dtime):  0.1
  Impact parameter: 2.79 fm
  Mass and Charge of Particles:
    Particle A - Mass: 197, Charge: 79
    Particle B - Mass: 197, Charge: 79
Total slices to process: 250
Data saved to ./outputs/parquet/event_2.parquet
Parsing completed, memory cleaned up.
Parsing and Parquet file creation completed successfully.
Parquet file loaded successfully.
Starting CSV conversion...
Conversion completed: 250 files created, 0 failed.
CSV conversion completed successfully.

ParaView Visualization

To visualize the output in ParaView:

1. Open ParaView:

   • Run ParaView and navigate to File -> Load State.
   • Load the assets/paraview/paraViewState-massVar.pvsm template.

2. Load the CSV File Sequence:

   • Right-click on event3_frame_0.csv* in the pipeline and select Change File.
   • Navigate to the csv_folder (default outputs/csv) and select your event file.
   • Right-click again on the file sequence in the pipeline and select Reload Files to refresh the list with the new files (Find new files).

3. Adjust Event Info and Time Annotation:

   • Update the event information in UrQMD-text.
   • Set the TimeAnnotation scaling based on your simulation step size with scale = step.

4. Enable Ray Tracing:

   • In the properties tab, enable ray tracing.

5. Save the Animation:

   • Go to File -> Save Animation.
   • Select a folder to save the PNG files for the animation.
   • Set the image resolution to 1920 x 1080 and choose a compression level (0 is recommended for no compression).

Example of the final result

auau-2-79-example-git.mp4