v1.1.1

.github/workflows/c-cpp.yml

@@ -10,10 +10,10 @@ jobs:
 
     steps:
     - name: Clone ParticleZoo repository
-      uses: actions/checkout@v4
+      uses: actions/checkout@v5
 
     - name: Setup Python
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: '3.x'
 
@@ -68,10 +68,10 @@ jobs:
 
     steps:
     - name: Clone ParticleZoo repository
-      uses: actions/checkout@v4
+      uses: actions/checkout@v5
 
     - name: Setup Python
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: '3.x'
 
@@ -126,19 +126,19 @@ jobs:
 
     steps:
     - name: Clone ParticleZoo repository
-      uses: actions/checkout@v4
+      uses: actions/checkout@v5
 
     - name: Setup MSVC
       uses: ilammy/msvc-dev-cmd@v1
 
     - name: Setup Python
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: '3.x'
 
     - name: Cache ROOT framework
       id: cache-root
-      uses: actions/cache@v4
+      uses: actions/cache@v5
       with:
         path: C:\root
         key: root-v6.36.04-win64-python311-vc17

.gitignore

@@ -1,6 +1,8 @@
 config.status
 build
 tests
+*.md
+!README.md
 .vscode
 .venv
 docs/latex
@@ -23,3 +25,4 @@ python/.tox/
 python/.venv/
 python/venv/
 python/ENV/
+.DS_Store

Doxyfile

@@ -48,7 +48,7 @@ PROJECT_NAME           = "ParticleZoo"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = v1.1
+PROJECT_NUMBER         = v1.1.1
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

docs/scripts/custom_doxygen.sty

@@ -78,14 +78,14 @@
 
   % Set text at the outside edge (LE = even-left, RO = odd-right)
   % Version number will be replaced by gendocs.sh
-  \fancyfoot[RE,LO]{\bfseries ParticleZoo Reference Manual v1.1}%
+  \fancyfoot[RE,LO]{\bfseries ParticleZoo Reference Manual v1.1.1}%
   \fancyfoot[LE,RO]{\bfseries \thepage}%
 
   % Also for 'plain' pages (chapter openings)
   % Version number will be replaced by gendocs.sh
   \fancypagestyle{plain}{%
     \fancyhf{}%
-    \fancyfoot[RE,LO]{\bfseries ParticleZoo Reference Manual v1.1}%
+    \fancyfoot[RE,LO]{\bfseries ParticleZoo Reference Manual v1.1.1}%
     \fancyfoot[LE,RO]{\bfseries \thepage}%
   }%
 }

docs/scripts/gendocs.sh

@@ -38,7 +38,7 @@ VERSION=$(gawk '
     }
 } 
 END {
-    version = "v" major "." minor
+    version = "v" major "." minor "." patch
     if (caveat != "" && caveat != " ") version = version " " caveat
     print version
 }' include/particlezoo/utilities/version.h)

include/particlezoo/IAEA/IAEAHeader.h

@@ -731,13 +731,13 @@ namespace ParticleZoo::IAEAphspFile
             bool                wIsStored_;
             bool                weightIsStored_;
 
-            float               constantX_;
-            float               constantY_;
-            float               constantZ_;
-            float               constantU_;
-            float               constantV_;
-            float               constantW_;
-            float               constantWeight_;
+            float               constantX_{};
+            float               constantY_{};
+            float               constantZ_{};
+            float               constantU_{};
+            float               constantV_{};
+            float               constantW_{};
+            float               constantWeight_{};
 
             std::vector<EXTRA_FLOAT_TYPE> extraFloatData_;
             std::vector<EXTRA_LONG_TYPE> extraLongData_;

include/particlezoo/IAEA/IAEAphspFile.h

@@ -59,6 +59,12 @@ namespace ParticleZoo::IAEAphspFile
              */
             std::uint64_t getNumberOfOriginalHistories() const override;
 
+            /**
+             * @brief Check if this format stores incremental history numbers per-particle.
+             * @return true if the header has an extra long of type INCREMENTAL_HISTORY_NUMBER
+             */
+            bool hasNativeIncrementalHistoryCounters() const override;
+
             /**
              * @brief Get the number of particles of a specific type
              * @param particleType Type of particle to count
@@ -241,6 +247,7 @@ namespace ParticleZoo::IAEAphspFile
     inline const IAEAHeader & Reader::getHeader() const { return header_; }
     inline std::uint64_t Reader::getNumberOfParticles() const { return header_.getNumberOfParticles(); }
     inline std::uint64_t Reader::getNumberOfOriginalHistories() const { return header_.getOriginalHistories(); }
+    inline bool Reader::hasNativeIncrementalHistoryCounters() const { return header_.hasExtraLong(IAEAHeader::EXTRA_LONG_TYPE::INCREMENTAL_HISTORY_NUMBER); }
     inline std::uint64_t Reader::getNumberOfParticles(ParticleType particleType) const { return header_.getNumberOfParticles(particleType); }
     inline std::size_t Reader::getParticleRecordStartOffset() const { return 0; }
     inline std::size_t Reader::getParticleRecordLength() const { return header_.getRecordLength(); }

include/particlezoo/PhaseSpaceFileReader.h

@@ -112,6 +112,25 @@ namespace ParticleZoo
              */
             virtual std::uint64_t getNumberOfRepresentedHistories() const;
 
+            /**
+             * @brief Check if this format can provide the number of represented histories
+             *        without scanning the file.
+             *
+             * @return true if getNumberOfRepresentedHistories() is cheap (e.g. stored in header)
+             */
+            virtual bool hasNativeRepresentedHistoryCount() const;
+
+            /**
+             * @brief Check if this format directly stores incremental history numbers per-particle.
+             *
+             * When true, particles returned by getNextParticle() carry the
+             * INCREMENTAL_HISTORY_NUMBER property with file-sourced values. Otherwise
+             * the incremental history numbers may be indirectly derived or otherwise determined.
+             *
+             * @return true if incremental history data is directly stored per-particle in this format
+             */
+            virtual bool hasNativeIncrementalHistoryCounters() const;
+
             /**
              * @brief Get the number of Monte Carlo histories that have been read so far.
              * If the end of the file has been reached, this will return the total number of original histories
@@ -623,6 +642,9 @@ namespace ParticleZoo
         throw std::runtime_error("getNumberOfRepresentedHistories() is not supported for this file format.");
     }
 
+    inline bool PhaseSpaceFileReader::hasNativeRepresentedHistoryCount() const { return false; }
+    inline bool PhaseSpaceFileReader::hasNativeIncrementalHistoryCounters() const { return false; }
+
     inline std::size_t PhaseSpaceFileReader::getParticleRecordLength() const {
         throw std::runtime_error("getParticleRecordLength() must be implemented for binary formatted file writers.");
     }

include/particlezoo/ROOT/ROOTphsp.h

@@ -138,6 +138,12 @@ namespace ParticleZoo::ROOT {
              */
             std::uint64_t getNumberOfOriginalHistories() const override;
 
+            /**
+             * @brief Check if this format stores incremental history numbers per-particle.
+             * @return true if the TTree has a history number branch
+             */
+            bool hasNativeIncrementalHistoryCounters() const override;
+
             /**
              * @brief Get format-specific CLI commands for ROOT configuration.
              * @return Vector of ROOT-specific CLI commands
@@ -209,6 +215,7 @@ namespace ParticleZoo::ROOT {
 
     inline std::uint64_t Reader::getNumberOfParticles() const { return numberOfParticles_; }
     inline std::uint64_t Reader::getNumberOfOriginalHistories() const { return numberOfOriginalHistories_; }
+    inline bool Reader::hasNativeIncrementalHistoryCounters() const { return treeHasHistoryNumber_; }
 
 
     /**

include/particlezoo/TOPAS/TOPASphspFile.h

@@ -49,6 +49,23 @@ namespace ParticleZoo::TOPASphspFile
              */
             std::uint64_t  getNumberOfOriginalHistories() const override;
 
+            /**
+             * @brief Get the number of represented histories in the phase space.
+             *
+             * Only available for ASCII and BINARY sub-formats (not LIMITED).
+             * For LIMITED, delegates to the base class which throws.
+             *
+             * @return Number of represented histories from the header
+             * @throws std::runtime_error if format is LIMITED
+             */
+            std::uint64_t  getNumberOfRepresentedHistories() const override;
+
+            /**
+             * @brief Check if this format can provide represented history count cheaply.
+             * @return true for ASCII and BINARY, false for LIMITED
+             */
+            bool hasNativeRepresentedHistoryCount() const override;
+
             /**
              * @brief Get the TOPAS format type of this file
              * @return TOPASFormat enum indicating ASCII, BINARY, or LIMITED
@@ -165,6 +182,15 @@ namespace ParticleZoo::TOPASphspFile
     // Inline implementations for the Reader class
     inline std::uint64_t Reader::getNumberOfParticles() const { return header_.getNumberOfParticles(); }
     inline std::uint64_t Reader::getNumberOfOriginalHistories() const { return header_.getNumberOfOriginalHistories(); }
+    inline std::uint64_t Reader::getNumberOfRepresentedHistories() const {
+        if (formatType_ == TOPASFormat::LIMITED) {
+            return PhaseSpaceFileReader::getNumberOfRepresentedHistories(); // throws
+        }
+        return header_.getNumberOfRepresentedHistories();
+    }
+    inline bool Reader::hasNativeRepresentedHistoryCount() const {
+        return formatType_ != TOPASFormat::LIMITED;
+    }
     inline TOPASFormat Reader::getTOPASFormat() const { return formatType_; }
     inline const Header & Reader::getHeader() const { return header_; }
     inline void Reader::setDetailedReading(bool enable) { readFullDetails_ = enable; }

include/particlezoo/parallel/HistoryBalancedParallelReader.h

@@ -8,6 +8,8 @@
 #include <string>
 #include <cstdint>
 #include <limits>
+#include <mutex>
+#include <atomic>
 
 namespace ParticleZoo {
 
@@ -131,6 +133,32 @@ namespace ParticleZoo {
              */
             std::uint64_t getHistoriesRead(size_t threadIndex) const;
 
+            /**
+             * @brief Gets the total number of particles processed by a specific thread.
+             *
+             * Returns the cumulative count of particles that have been read by this thread.
+             *
+             * @param threadIndex The index of the thread (0 to numThreads-1)
+             * @return Total number of particles processed
+             *
+             * @throws std::out_of_range If threadIndex is invalid
+             */
+            std::uint64_t getParticlesRead(size_t threadIndex) const;
+
+            /**
+             * @brief Gets the total number of particles read across all threads.
+             * 
+             * @return Total number of particles read
+             */
+            std::uint64_t getTotalParticlesRead() const;
+
+            /**
+             * @brief Gets the total number of original histories read across all threads.
+             *
+             * @return Total number of original histories read
+             */
+            std::uint64_t getTotalHistoriesRead() const;
+
             /**
              * @brief Gets the total number of particles in the phase space file.
              * 
@@ -159,6 +187,27 @@ namespace ParticleZoo {
              */
             std::uint64_t getNumberOfRepresentedHistories() const { return numberOfRepresentedHistories_; }
 
+            /**
+             * @brief Gets the number of threads used by this reader.
+             *
+             * @return Number of parallel threads
+             */
+            std::size_t getNumberOfThreads() const { return readers_.size(); }
+
+            /**
+             * @brief Checks if the underlying phase space format provides native represented history count.
+             * 
+             * @return True if native represented history count is available, false otherwise
+             */
+            bool hasNativeRepresentedHistoryCount() const;
+
+            /**
+             * @brief Checks if the underlying phase space format provides native incremental history counters.
+             * 
+             * @return True if native incremental history counters are available, false otherwise
+             */
+            bool hasNativeIncrementalHistoryCounters() const;
+
             /**
              * @brief Closes all underlying phase space file readers.
              * 
@@ -168,20 +217,28 @@ namespace ParticleZoo {
             void     close();
 
         private:
+            struct ThreadStatistics {
+                mutable std::mutex mutex; // For thread-safe updates
+                std::atomic<std::uint64_t> particlesRead = 0;
+                std::atomic<std::uint64_t> totalHistoriesRead = 0;
+                // Per-thread-only fields (no cross-thread access needed)
+                std::uint64_t historiesRead = 0;
+                std::uint64_t emptyHistoryError = 0;
+                HasMoreParticlesResult hasMoreParticlesCache = NEEDS_CHECKING;
+            };
+
             std::vector<std::shared_ptr<PhaseSpaceFileReader>> readers_;
+            std::vector<std::unique_ptr<ThreadStatistics>> threadStats_;
+            std::vector<std::uint64_t> startingHistorys_;
 
+            bool hasNativeRepresentedHistoryCount_;
+            bool hasNativeIncrementalHistoryCounters_;
             bool hasGapsBetweenHistories_;
-            std::uint64_t totalHistoriesToRead_;
             std::uint64_t numberOfOriginalHistories_;
             std::uint64_t numberOfParticlesInPhsp_;
             std::uint64_t numberOfRepresentedHistories_;
             std::uint64_t emptyHistoriesBetweenEachHistory_;
             std::uint64_t perHistoryErrorContribution_;
-            std::vector<std::uint64_t> emptyHistoryErrors_;
-            std::vector<std::uint64_t> startingHistorys_;
-            std::vector<std::uint64_t> historiesRead_;
-            std::vector<std::uint64_t> totalHistoriesRead_;
-            std::vector<HasMoreParticlesResult> hasMoreParticlesCache_;
     };
 
 }