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.
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:
Example usage:
Alternatives
already depends on.
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.
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.