Tutorial: A Guide to Visualizing Your Results

Table of Contents

• 1. Understanding Your Output Files
  • 1.1. Common Data Fields
• 2. The ParaView Interface
• 3. Recipes for Visualizing Grid Data (.vts files)
  • 3.1. Recipe: Coloring by a Scalar Field
  • 3.2. Recipe: Creating a Cross-Section (Slice)
  • 3.3. Recipe: Showing Velocity Vectors (Glyphs)
  • 3.4. Recipe: Tracing Flow Paths (Streamlines)
• 4. Recipes for Visualizing Particle Data (.vtp files)
• 5. Saving Your Work
• 5.1 Practical Notes
• 6. Next Steps

The previous tutorials showed you specific steps to visualize the flat_channel and bent_channel cases. This guide provides a more general introduction to ParaView, the recommended tool for analyzing PICurv's output.

Here, you will learn the fundamental skills needed to explore any simulation result you generate, from inspecting data fields to creating publication-quality images and animations.

1. Understanding Your Output Files

After a successful run, the postprocessor writes visualization files under <run.visualization>/<recipe_id>/. The recipe id combines a readable output prefix with a stable digest of the recipe, so repeated use resumes the same result while different recipes coexist. post.yml -> io.output_directory is runtime-managed and cannot redirect output outside this home.

You will typically find:

• **Physical-time collections (.pvd files):** When post.yml -> io.paraview_series.enabled: true, open the collection named after the output prefix, such as eulerian_data.pvd or Particle.pvd. Its time axis comes from committed checkpoints. With scope: lineage, it also references compatible visualization files in ancestor runs recorded by --restart-from.
• **Eulerian Grid Data (.vts files):** These are VTK Structured Grid files (e.g., Field_000100.vts). They contain the computational mesh and any data fields that live on that grid, such as velocity and pressure. When you open them in ParaView, they will be grouped as a time series.
• **Lagrangian Particle Data (.vtp files):** These are VTK PolyData files (e.g., Particle_000100.vtp). They contain particle coordinates and particle fields. These files exist only when post.yml -> io.output_particles: true.

1.1. Common Data Fields

When you load a .vts file, you'll be able to color and analyze several data fields. The most common ones generated by the standard_analysis.yml recipe are:

• Ucat_nodal: A 3-component vector representing the fluid velocity at the grid nodes. This is the primary field you will use for visualizing the flow.
• P_nodal: A scalar representing the pressure field at the grid nodes.
• Qcrit_nodal: A scalar representing the Q-criterion averaged to grid nodes, a value used to identify vortices and turbulent structures in the flow.

2. The ParaView Interface

ParaView's interface has four key areas you will interact with constantly:

1. Pipeline Browser (Top Left): This shows your data and any "filters" you've applied. You click on an item here to make it active.
2. Properties Panel (Bottom Left): This is where you configure the selected data or filter. You must click the green "Apply" button in this panel after making changes.
3. 3D View (Center): Your visualization.
4. Toolbar (Top): Provides quick access to common data sources and filters.

3. Recipes for Visualizing Grid Data (.vts files)

Let's walk through the most common visualization techniques for the Eulerian grid data. Open the Eulerian .pvd collection and click Apply. If collection generation is disabled, open the numbered .vts group instead; filename grouping alone does not provide the checkpoint physical-time axis.

3.1. Recipe: Coloring by a Scalar Field

By default, the object is shown as a solid color. To color it by pressure:

1. In the toolbar, find the Coloring dropdown (it says "Solid Color").
2. Change it to P_nodal.
3. The object will now be colored, and a color bar (or "Scalar Bar") will appear. You can edit the color map by clicking the "Edit color map" button (a folder with a rainbow).

3.2. Recipe: Creating a Cross-Section (Slice)

To see what's happening inside the domain:

1. Make sure your Field..vts data is selected in the Pipeline Browser.
2. Click the Slice filter icon in the toolbar.
3. A plane will appear in the 3D view. In the Properties panel, you can drag the handles on the plane to move it, or change its Normal vector to orient it (e.g., Normal X Normal gives a slice perpendicular to the x-axis).
4. Click Apply. You now have a 2D slice that you can color just like any other object.

3.3. Recipe: Showing Velocity Vectors (Glyphs)

To visualize the direction and magnitude of the flow:

1. Select your Field..vts data (or a Slice).
2. Click the Glyph filter icon in the toolbar.
3. In the Properties panel:
   • Set Orientation Array to Ucat_nodal. This tells ParaView to align the glyphs with the velocity vectors.
   • Set Scale Array to Ucat_nodal. This will scale the glyphs by velocity magnitude.
   • Under "Scaling", adjust the Scale Factor to make the arrows smaller or larger.
   • Under "Masking", you can reduce the Glyph Mode from "All Points" to "Every Nth Point" to avoid cluttering the view.
4. Click Apply. You can now see arrows representing the flow field.

3.4. Recipe: Tracing Flow Paths (Streamlines)

1. Select your Field..vts data.
2. Click the Stream Tracer filter icon.
3. The "Seed" is the source of the streamlines. By default, it's a line. Drag the endpoints of the line in the 3D view to place it at the inlet of your domain.
4. In the Properties panel, increase the Resolution of the seed line to generate more streamlines.
5. Click Apply. You can now color the streamlines by velocity or pressure.

4. Recipes for Visualizing Particle Data (.vtp files)

Load Particle.pvd (if present) to visualize the Lagrangian particles with physical time. Without a collection, load the numbered Particle..vtp group.

1. Change Representation: In the Properties panel, find the Representation dropdown. Change it from "Surface" to Point Gaussian. This will render the particles as spheres. You can adjust the Gaussian Radius to change their size.
2. Color by Velocity: Use the Coloring dropdown in the toolbar to color the particles by velocity and Magnitude.

5. Saving Your Work

• To save an image: Go to File -> Save Screenshot.
• To save a video: Go to File -> Save Animation. Choose your resolution and frame rate, and ParaView will generate a video file by playing through all the timesteps.

5.1 Practical Notes

• File prefixes are configurable in post.yml (output_filename_prefix, particle_filename_prefix), so your series may not always be named Field_* and Particle_*.
• If particles were disabled in solver or post (output_particles: false), absence of .vtp files is expected.
• Statistics pipeline outputs (e.g., MSD CSV) are analysis files, not ParaView geometry files.

To enable collections in an existing post recipe, add:

io:
  paraview_series:
    enabled: true
    scope: lineage

Merge this block into the recipe's existing io mapping. Use scope: run for a collection confined to one run. Omitting the option disables collections; the standard analysis profiles explicitly enable them.

Run the usual post-processing command, keeping the full desired analysis window. Postprocess ancestors with the same recipe before processing the child. Open the child's collection to see the retained ancestor frames followed by the child frames; the child owns the restart step. Repeating the post command updates the collection with the steps the solver has committed since. Reopen the collection in ParaView to load its refreshed contents. Keep the referenced run directories accessible: the PVD contains relative links, not copies of the VTK data.

See Configuration Reference: Postprocessor YAML for recipe compatibility, cadence, and restart reset rules. In particular, changing the post stride creates a different recipe; the index does not search other recipe directories automatically.

6. Next Steps

You are now equipped with the basic skills to install, run, and analyze any simulation in PICurv.

The "Getting Started" section is complete. You are ready to become a Power User. Proceed to the User Guide to begin learning how to create your own custom simulations from scratch.