v1.1.0

[dobrienphd]

ParticleZoo v1.1.0

Version bump: v1.0.2 -> v1.1.0

---

Summary

This release introduces multi-threaded parallel phase space reading, comprehensive Python bindings, additional particle filtering for CLI tools, EGS LATCH and PENELOPE ILB interpretation infrastructure, a drop-in Geant4 primary generator action, and CI/CD pipelines for Linux, macOS, and Windows. Together these represent a major feature expansion of ParticleZoo across the library, CLI tools, and ecosystem.

---

Major Features

1. Multi-Threaded Parallel Phase Space Readers

Two new parallel reader classes enable thread-safe, lock-free reading of phase space files by partitioning the file across independent reader instances:

• HistoryBalancedParallelReader — Distributes histories evenly across threads. Ideal for use-cases where the history is the fundamental unit of work.
• ParticleBalancedParallelReader — Distributes particles evenly across threads (with history boundary alignment). Best for optimal load-balancing.

Both readers support peekNextParticle(), getNextParticle(), hasMoreParticles(), per-thread history/particle counters, and expose file-level metadata (total particles, original histories, represented histories).

New source files: src/parallel/HistoryBalancedParallelReader.cc, src/parallel/ParticleBalancedParallelReader.cc, and corresponding headers under include/particlezoo/parallel/.

2. Python Bindings

A complete Python package (particlezoo) built with pybind11 exposes the core C++ API to Python 3.8+:

• Full Particle class with property-style access (position, momentum, energy, weight, type, etc.)
• PhaseSpaceFileReader / PhaseSpaceFileWriter via create_reader() / create_writer() factory functions
• Pythonic iterator protocol (for particle in reader:)
• All ParticleType, IntPropertyType, FloatPropertyType, BoolPropertyType enums
• PDG code helpers, unit constants, UserOptions, and ArgParser
• Format-specific features: EGS LATCH and PENELOPE ILB access
• Comprehensive README with installation instructions (venv, pip, Makefile targets) and examples

New Makefile targets: make install-python, make install-python-dev, make uninstall-python.

Python examples in examples/python: read_phase_space.py, write_phase_space.py.

3. Additional Particle Filtering in PHSPConvert

PHSPConvert has been significantly expanded from a basic format converter to a full-featured particle filter/converter. All new filtering options:

• Particle type: --photonsOnly, --electronsOnly, --filterByPDG <code>
• Energy range: --minEnergy, --maxEnergy (in MeV)
• Position range: --minX/maxX, --minY/maxY, --minZ/maxZ (in cm)
• Radial distance: --minRadius, --maxRadius (XY plane, in cm)
• Generation: --primariesOnly, --excludePrimaries, --generations <min> <max>
• Constants: --preserveConstants (now a bool argument, defaults to true)
• Error control: --errorOnWarning (return non-zero exit code on warnings)

The internal architecture was refactored from inline parsing into a structured AppConfig class with centralized validation and a standalone applyFilters() function. Errors and warnings are now tracked separately, and the error/warning distinction was corrected (mismatched particle counts are now warnings, not errors).

4. PHSPImage Enhancements

PHSPImage was significantly refactored for readability and extended with new capabilities:

• Multiple scoring quantities: --score count|energy|xDir|yDir|zDir (replaces --energyWeighted for broader fluence analysis)
• Generation filtering: --primariesOnly, --excludePrimaries, --generations
• EGS LATCH filtering: --EGS-latch-filter bitmask support
• Error control: --errorOnWarning
• Internal reorganization into anonymous namespace with structured AppConfig

5. Geant4 Integration Example

A complete, ready-to-use G4VUserPrimaryGeneratorAction implementation for reading phase space files in Geant4 simulations:

• Uses ParticleBalancedParallelReader for multi-threaded Geant4 runs
• Supports incremental history handling with proper event skipping
• Global translation and rotation (with optional center of rotation for isocenter-based gantry/collimator rotations)
• Particle recycling with automatic weight adjustment

Files: examples/geant4/G4PHSPSourceAction.hh, examples/geant4/G4PHSPSourceAction.cc.

---

Library API Additions

Particle Class

• getPDGCode() — Convenience method returning the PDG identification code for the particle type
• isPrimary() — Returns true if the particle has GENERATION == 1
• setGeneration(int) — Sets the GENERATION integer property
• Double-precision constructor — New overload accepting double arguments, internally converts to float
• IntPropertyType::GENERATION — New standard integer property type for particle generation tracking (1 = primary, 2+ = secondary)
• BoolPropertyType::IS_SECONDARY_PARTICLE — Deprecated in favor of IntPropertyType::GENERATION

PhaseSpaceFileReader

• peekNextParticle() — Reads the next particle without advancing the file position
• getNumberOfRepresentedHistories() — Virtual method for the count of histories that actually produced particles (distinct from "original" histories which include empty ones)
• peekParticleManually() — Override point for formats with custom I/O (implemented for ROOT)

PhaseSpaceFileWriter

• --flipX, --flipY, --flipZ — New CLI commands to negate directional cosines on write

ByteBuffer

• peekBytes(len) — Returns a std::span of the next len bytes without advancing the read offset

PDGParticleCodes

• getAllParticleTypes() — Returns the complete list of (name, ParticleType) pairs (used by Python bindings)

---

EGS LATCH & PENELOPE ILB Infrastructure

New header: include/particlezoo/egs/EGSLATCH.h

• EGSLATCHOPTION enum (options 1, 2, 3 per EGS documentation)
• ApplyLATCHToParticle() — Decodes LATCH bits into particle properties (multi-crosser, generation)
• ExtractLATCHFromParticle() — Constructs a LATCH value from particle properties
• DoesParticlePassLATCHFilter() — Bitmask-based LATCH filtering
• --EGS-latch-option and --EGS-latch-filter CLI commands

New header: include/particlezoo/penelope/ILBArray.h

• ApplyILB[1-5]ToParticle() / ExtractILB[1-5]FromParticle() — Individual ILB accessor/mutator functions
• ApplyILBArrayToParticle() / ExtractILBArrayFromParticle() — Batch operations for the 5-element ILB array
• Proper ILB1-to-GENERATION mapping (ILB1 encodes particle generation in PENELOPE)

All reader/writers that support these values now use these centralized routines instead of ad-hoc inline logic, ensuring consistency when converting between formats.

---

Argument Parsing (argParse.h)

• UserOptions promoted to a class (from a using alias) with typed extraction methods: extractPositional(), extractStringOption(), extractIntOption(), extractUIntOption(), extractFloatOption(), extractBoolOption()
• CLI_UINT argument type — New unsigned integer argument support
• CLIValue variant — Now includes unsigned int
• std::string_view overloads for PrintUsage() and ParseArgs()
• UserOptions initializer list constructor — For backwards compatibility with v1.0 API

---

Build System & CI

CI/CD Pipeline (.github/workflows/c-cpp.yml)

New GitHub Actions workflow testing on all three platforms:

• Linux (ubuntu-latest): Build with and without ROOT, install, verify CLI tools, install and smoke-test Python bindings
• macOS (macos-latest): Same as Linux, ROOT via Homebrew
• Windows (windows-latest): MSVC build, ROOT via cached download, Python bindings test

Windows Build Script (build.bat)

• ROOT support: Auto-detection via root-config, include path extraction, warning suppression for ROOT headers, proper /link prefix stripping for ROOT library flags
• --no-root flag: Disable ROOT even if available
• Architecture specification for MSVC (-arch x64)

Makefile

• Parallel reader source files added to library build
• -Wno-deprecated-declarations added to both release and debug flags (for IS_SECONDARY_PARTICLE deprecation)
• Python installation/uninstallation targets

Other

• .gitattributes updated to export-ignore GitHub workflows and additional directories
• .gitignore updated for Python artifacts, build outputs, and test files

---

Documentation

• Updated reference manual PDF to v1.1 (dropped patch release version for manual)
• Updated test summary PDF to v1.1.0
• Comprehensive Python bindings README (python/README.md)
• Updated main README with parallel reader documentation, Python bindings section, expanded CLI examples, generation tracking API, unit system reference, and Windows build instructions
• Doxygen API documentation generation script for Python (docs/scripts/gen_python_api.py)

---

Breaking Changes

• BoolPropertyType::IS_SECONDARY_PARTICLE is now deprecated (compiles with a warning). Use IntPropertyType::GENERATION instead.
• UserOptions is now a class (inheriting from std::unordered_map) rather than a type alias — existing code using it as a map should still compile.
• maxParticles CLI argument type changed from CLI_INT to CLI_UINT in PHSPConvert, PHSPCombine, and PHSPImage.
• PHSPConvert now separates errors from warnings; previously all issues were reported as warnings.