Skip to content

lost particle h5 files to vtkhdf to allow visualization in paraview #3922

Description

@shimwell

Description

Lost particle restart files (particle_*.h5) contain useful diagnostic information (position, direction, energy, weight) but have no built-in way to visualize them.
The existing openmc.Particle class in particle_restart.py is a read-only data container with no export functionality.

Particle tracks (tracks.h5) already support VTK export via Tracks.write_to_vtk(), but this outputs VTP format and requires the vtk Python package. Lost particles
have no equivalent.

Add a method to write one or more lost particle files to a single VTK HDF PolyData file (.vtkhdf). This would allow users to visualize where particles are being lost
by opening the file directly in ParaView. The VTK HDF format is preferable to VTP because it only requires h5py and numpy (both existing OpenMC dependencies) rather
than the vtk package.

The output file would store:

  • Point positions (xyz) as the geometry
  • Point data arrays for energy, weight, direction (uvw), particle type, batch, generation, and particle ID

Example usage:

  openmc.Particle.write_vtkhdf(
      ['particle_1_285880.h5', 'particle_1_300145.h5'],                                                                                                                
      'lost_particles.vtkhdf'
  )                                                                                                                                                                    

Alternatives

  • VTP format: Would match the existing Tracks.write_to_vtk() approach but adds a dependency on the vtk Python package. VTK HDF only needs h5py and numpy which OpenMC
    already depends on.
  • Modify the C++ to write VTK HDF directly: Currently each lost particle writes its own file immediately inside an omp critical section. Collecting all lost
    particles into a single VTK HDF file at simulation end would require accumulating data in a thread-safe buffer and changes to the simulation finalization logic. A
    Python post-processing approach is simpler and non-invasive.
  • A standalone function rather than a class method: A static/class method on openmc.Particle keeps it discoverable alongside the existing lost particle API.

Compatibility

This adds a new static method to openmc.Particle — no existing APIs are changed. The current lost particle file format and restart functionality are unaffected.

Activity

  1. shimwell commented on Apr 14, 2026

    @shimwell
    MemberAuthor

    @rherrero-pf I think this is the feature needed to help track down lost particles.

  2. paulromano commented on Jul 17, 2026

    @paulromano
    Contributor

    Lost particle restart files are not intended to be visualized because they don't actually tell you where a particle was lost. Rather, they contain the source information needed to restart a particle in order to reproduce the sequence of events that led to the particle being lost. For example, if you have a model where you are getting lost particles and your source definition is a point source, visualizing the lost particle restart files would just show you that point source, which is not terribly useful!

    @viktormai and I are currently working on trying to improve the situation by having OpenMC automatically produce a track file for any particles that were lost (see #3976 for a draft — still needs work but gives you the basic idea). Along with that, we're also planning on integrating it into the plotter application so that you can overlay lost particle tracks on a geometry visualization. With that in mind, I'm going to go ahead and close this issue and the associated PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions