Update io_formats documentation for track files (and file version)

docs/source/io_formats/track.rst

@@ -4,18 +4,27 @@
 Track File Format
 =================
 
-The current revision of the particle track file format is 2.0.
+The current revision of the particle track file format is 3.0.
 
 **/**
 
 :Attributes: - **filetype** (*char[]*) -- String indicating the type of file.
              - **version** (*int[2]*) -- Major and minor version of the track
                file format.
-             - **n_particles** (*int*) -- Number of particles for which tracks
-               are recorded.
-             - **n_coords** (*int[]*) -- Number of coordinates for each
-               particle.
 
 :Datasets:
-           - **coordinates_<i>** (*double[][3]*) -- (x,y,z) coordinates for the
-             *i*-th particle.
+           - **track_<b>_<g>_<p>** (Compound type) -- Particle track information
+             for source particle in batch *b*, generation *g*, and particle
+             number *p*. particle. The compound type has fields ``r``, ``u``,
+             ``E``, ``time``, ``wgt``, ``cell_id``, and ``material_id``, which
+             represent the position (each coordinate in [cm]), direction, energy
+             in [eV], time in [s], weight, cell ID, and material ID,
+             respectively.
+
+             :Attributes: - **n_particles** (*int*) -- Number of
+                            primary/secondary particles for the source history.
+                          - **offsets** (*int[]*) Offset into the array for each
+                            primary/secondary particle.
+                          - **particles** (*int[]*) -- Particle type for each
+                            primary/secondary particle (0=neutron, 1=photon,
+                            2=electron, 3=positron).

include/openmc/constants.h

@@ -26,7 +26,7 @@ constexpr int HDF5_VERSION[] {3, 0};
 // Version numbers for binary files
 constexpr array<int, 2> VERSION_STATEPOINT {17, 0};
 constexpr array<int, 2> VERSION_PARTICLE_RESTART {2, 0};
-constexpr array<int, 2> VERSION_TRACK {2, 0};
+constexpr array<int, 2> VERSION_TRACK {3, 0};
 constexpr array<int, 2> VERSION_SUMMARY {6, 0};
 constexpr array<int, 2> VERSION_VOLUME {1, 0};
 constexpr array<int, 2> VERSION_VOXEL {2, 0};

openmc/trackfile.py

@@ -2,11 +2,14 @@ from collections import namedtuple
 
 import h5py
 
+from .checkvalue import check_filetype_version
 from .source import SourceParticle, ParticleType
 
 
 ParticleTrack = namedtuple('ParticleTrack', ['particle', 'states'])
 
+_VERSION_TRACK = 3
+
 
 def _identifier(dset_name):
     """Return (batch, gen, particle) tuple given dataset name"""
@@ -112,12 +115,15 @@ class TrackFile(list):
     def __init__(self, filepath):
         # Read data from track file
         with h5py.File(filepath, 'r') as fh:
+            # Check filetype and version
+            check_filetype_version(fh, 'track', _VERSION_TRACK)
 
             for dset_name in sorted(fh, key=_identifier):
                 dset = fh[dset_name]
                 self.append(Track(dset))
 
     def plot(self):
+        """Produce a 3D plot of particle tracks"""
         import matplotlib.pyplot as plt
         fig = plt.figure()
         ax = plt.axes(projection='3d')