v0.3.0

PYGEMC Release 0.3.0

This version includes:

• y-vs-x hit-position maps in the analyzer (plot_y_vs_x, gemc-analyzer --plot yvsx)
• Reading of the generated-particle kinematics stream (generated_tracked)
• GVolume.distribute_on_circle() to replicate a volume around a circle
• GVolume.g4placement_type to select the active/passive Geant4 placement convention
• Configurable PyVista background colors with a new dark-navy default
• PyVista visualization of G4Trap, G4Sphere, and G4Polycone solids
• New scintillator_barrel example (48-paddle ring)
• gemc-sqlite -n to create an empty GEMC database
• GConfiguration now tracks all variations used in a run

Release notes

Analyzer

• Added y-vs-x hit-position maps: plot_y_vs_x() and gemc-analyzer --plot yvsx, with --x/--y
  coordinate selection (defaults avgx/avgy), --ylim to complement --xlim, and
  --position-unit {mm,cm} (default cm).
• Added reading of the _generated_tracked.csv GEMC output stream, exposing the generated particle
  kinematics (p, theta, phi) as generated_tracked data and adding it to the --data choices.
• plot_variable() now falls back to the generated_tracked stream when the selected stream is
  empty/missing or lacks the requested variable, so generated theta, phi, and p plot without extra
  arguments (even with the default --data digitized).
• Added available_variables() and GemcOutput.variables() to report the plottable quantities per
  stream; running gemc-analyzer <file> without a variable prints the plottable <stream>: ... list.

API

• Added GVolume.distribute_on_circle(n, radius, phistart=0, phispan=360, align=False, axis='z', lunit='mm', aunit='deg') to replicate a volume at n equal angular steps along a circle of the given
  radius. Returns a list[GVolume], one copy per step, each named <name>_i. With align=True, each
  copy stays radially aligned using GEMC's doubleRotation: format.
• Added GVolume.g4placement_type to select the Geant4 placement convention: 'active' (default,
  G4Transform3D, the Geant4 standard) or 'passive' (frame-rotation G4PVPlacement, matching the
  GEMC2/clas12Tags convention). The selected mode is stored in the SQLite database and drives the
  placement constructor used during simulation.
• Added configurable PyVista background: -pvbg/--pyvista-background-color for the base color and
  -pvbgt/--pyvista-background-top for the optional top gradient (use -pvbgt none for a flat
  background). The default background changed from "white" to "#00122B" (dark navy); restore white
  with -pvbg white.
• Added G4Trap, G4Sphere, and G4Polycone PyVista visualization support.
• Added parse_rotation_string() to interpret GEMC rotation strings in simple xyz, ordered-axis, and
  compound (add_rotation/doubleRotation:) forms, so volumes placed with
  distribute_on_circle(align=True) render with the correct per-copy orientation.
• Upcoming in the next release: geometry scripts can use --read-yaml to apply g4camera direction and
  g4view.background settings to PyVista rendering.
• Added gemc-sqlite -n <filename> to create a new empty SQLite database with the full GEMC geometry and
  materials schema.
• GConfiguration now tracks all variations used during a run in a self.variations list. show()
  prints all variations instead of only the last one; the label switches from Variation to
  Variations when more than one was used.

Documentation

• Added Structure Helpers documentation
  page covering distribute_on_circle: parameter reference, position formula per axis, alignment rotation
  semantics, and the chord-sizing derivation with a worked scintillator barrel example.
• Added scintillator_barrel example page with interactive VTK.js viewer (48 paddles), end-on PyVista
  screenshot, and gemc-analyzer plots for totEdep and true track energy.
• Documented gemc-analyzer --plot yvsx usage and PyVista background controls in the README, with an
  example command using --xlim -20 20 --ylim -20 20.
• Added gemc-sqlite to the README features list and a full ### gemc-sqlite section under Command-Line
  Tools.
• Documented environment activation (source <prefix>/python_env/bin/activate) and clarified that
  /opt/homebrew/bin/python3 should be used when creating virtual environments on macOS with Homebrew.
• Updated the Cherenkov example documentation to describe neutral radiator names, demonstration optical
  constants, and the one-generated-electron quick analyzer workflow.

Examples

• Added scintillator_barrel: 48 trapezoidal G4Trap paddles distributed in a full ring using
  distribute_on_circle(align=True, axis='z'). Demonstrates the chord-sizing formula that makes adjacent
  outer faces contiguous for any paddle count, and the flux digitization with per-paddle identifiers.

Tests

• Added analyzer unit coverage for y-vs-x axis limits and centimeter labels.
• Added analyzer CLI coverage that writes a tiny true-info CSV, runs --plot yvsx --save, and verifies
  that a PNG is produced.

Addressed issues

• Issue #1: fix Python API gconfiguration

Supported platforms

• Linux
• macOS

Dependencies

• Python 3.10 or higher
• numpy, pandas, matplotlib
• uproot and awkward for optional ROOT-file analysis via the root extra

Compatibility notes

• Existing histogram usage remains the default analyzer behavior.
• The new y-vs-x CLI mode does not require a positional variable argument.

Detailed list of changes and fixes

• Exported plot_y_vs_x from pygemc.analyzer and wired --plot yvsx into the analyzer CLI.
• Updated the analyzer README examples.
• Registered gemc-sqlite as a console-script entry point in pyproject.toml.
• Fixed an uninitialized experiment_filter variable in gsqlite.main() that raised a NameError when
  -ef was not supplied.
• Stored g4placement_type in the SQLite database schema.
• The doubleRotation: branch of parse_rotation_string() left-multiplies two sequential xyz rotations
  to match the GEMC C++ rotateX/Y/Z call order.
• Added _axis_rotation_matrix(), add_general_trap(), add_sphere(), add_polycone() (and the
  internal _add_polycone_from_gvolume()) to pyvista_api.py; the volume dispatch now handles the
  G4Trap, G4Sphere, and G4Polycone solid types.
• PyVista placement applies the transpose of the rotation matrix for 'passive' volumes so world-frame
  positions render correctly.
• Added scintillator_barrel (scintillator_barrel.py, scintillator_barrel.yaml) to
  src/examples/basic/ and registered it in the examples/meson.build test map.
• Aligned ASCII output columns in gvolume.py and gmaterial.py for improved readability.
• Renamed the downstream trigger workflow to source tests (trigger_src_tests.yml) and kept CI workflow
  path filters aligned with governance-only documentation changes.