Dev Nightly

Commits on main since 2026-06-17

• 2026-07-13 f32759f - fixed unit on system template particle (by Maurizio Ungaro)
• 2026-07-10 21b1c87 - fixed tests after introducing boolean operations and paraboloid (by Maurizio Ungaro)
• 2026-07-09 9d0b0a5 - registered boolean operations (by Maurizio Ungaro)
• 2026-07-09 d3f3555 - mirrors and paraboloid (by Maurizio Ungaro)
• 2026-07-09 655d4a9 - added mirrors (by Maurizio Ungaro)
• 2026-07-08 d7382cd - simplified UI, inferring file type from format. (by Maurizio Ungaro)
• 2026-07-07 2000fed - ci test fix and mesh wire representation (by Maurizio Ungaro)
• 2026-07-07 7dafebb - CAD volume definitions in a single YAML/JSON file and PyVista rendering for SQLite CAD volumes (by Maurizio Ungaro)
• 2026-07-02 7ff91db - fixed release notes (by Maurizio Ungaro)
• 2026-06-30 490e486 - release consolidated (by Maurizio Ungaro)
• 2026-06-30 458fb03 - added plotting of smeared quantities (by Maurizio Ungaro)
• 2026-06-30 18d4f35 - Added a regression test covering set_rotation - addressed issue 3 (by Maurizio Ungaro)
• 2026-06-30 e995abf - added one-two rotation test - addressed issue 2 (by Maurizio Ungaro)
• 2026-06-25 c46d0f0 - added docker badges (by Maurizio Ungaro)
• 2026-06-23 8448d3a - fixed self.rotations is a list invariant reconciled with the newer alignment and sqlite code - this was issue #9 (by Maurizio Ungaro)
• 2026-06-23 63c89f7 - Merge pull request #12 from zhaozhiwen/fix/122-gconfiguration-args (by Mauri)
• 2026-06-23 237e20d - Merge branch 'main' into fix/122-gconfiguration-args (by Mauri)
• 2026-06-22 576abbc - added sqlite and pyvista tests (by Maurizio Ungaro)
• 2026-06-21 96c8929 - Merge pull request #11 from zhaozhiwen/fix/120-make-trap-self (by Mauri)
• 2026-06-21 ff90d25 - Merge pull request #10 from zhaozhiwen/fix/119-polycone-length-check (by Mauri)
• 2026-06-19 4787b31 - new license and citations files (by Maurizio Ungaro)
• 2026-06-18 45dcdb2 - added fast PyVista rendering and pyvista variation selection (by Maurizio Ungaro)
• 2026-06-18 4863be5 - Merge pull request #14 from zhaozhiwen/fix/139-convert-angle-gon (by Mauri)
• 2026-06-17 5c0ac5c - automatic pypi publish (by Maurizio Ungaro)
• 2026-06-17 32152e0 - updated since and added release template (by Maurizio Ungaro)
• 2026-06-17 17e538e - ready for release (by Maurizio Ungaro)

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.

v0.2.0

pygemc v0.2.0 prepares the Python API for standalone package distribution, improves documentation, and tightens CI/release integration with GEMC.

Release notes

This release keeps the core geometry and analyzer APIs from v0.1.0 and focuses on making pygemc easier to install, document, test, and release independently from the main GEMC source tree.

Packaging and installation

• Prepared pygemc for stable PyPI publishing with Hatch / hatch-vcs packaging.
• Added stable-tag version detection restricted to vX.Y.Z tags, so the moving dev tag does not affect package versions.
• Added the GEMC Software License to the package and configured packaging metadata to use LICENSE.md.
• Updated package author contact to ungaro@jlab.org.
• Documented virtual-environment based installation using python -m pip.
• Documented stable PyPI installation:
  • python -m pip install pygemc
  • python -m pip install "pygemc[root]"
• Documented development snapshot installation from GitHub:
  • python -m pip install "pygemc @ git+https://github.com/gemc/pygemc.git@dev"
• Documented editable local-clone development installs:
  • python -m pip install -e ".[dev]"
  • python -m pip install -e ".[dev,root]"

Release workflow

• Added a nightly GitHub-only dev prerelease workflow.
• Added generated development release notes in releases/dev.md.
• Added ci/update-devmd.sh to build dev release notes from commits since a fixed date.
• Added a manual publish_pypi.yml workflow for stable tagged releases only.
• Kept development releases off PyPI; the moving dev release is installable from GitHub.
• Added support for publishing to TestPyPI before publishing to PyPI.

Documentation

• Rewrote the README with a full project overview, feature list, installation paths, quickstart, geometry API example, command-line tools, analyzer usage, tests, project layout, documentation links, contribution notes, and license information.
• Added CI, Python, PyPI, license, and documentation badges.
• Added a PyVista visualization gallery with linked thumbnails for B1, B2, Materials, and Simple Flux examples.
• Linked gallery thumbnails to hosted VTK.js scenes generated from .vtksz files.
• Clarified that GitHub README files cannot embed .vtksz scenes inline.

Governance and project metadata

• Added CODE_OF_CONDUCT.md.
• Added CONTRIBUTING.md with a fork-and-pull-request workflow.
• Added SECURITY.md with vulnerability reporting instructions.
• Standardized feedback, security, and conduct contact email to ungaro@jlab.org.
• Updated the GEMC Software License coverage through 2026.

CI

• Renamed and clarified the Python test workflow.
• Added a workflow to trigger the GEMC source Docker deploy/test workflow after pygemc changes.
• Added workflow path filters so README and governance-document changes do not trigger CI.
• Kept automated tests on Python 3.10 and 3.14.

Build-system integration

• Updated Meson subproject behavior so the parent GEMC build can install pygemc without unnecessary isolated-build PyPI fetches.
• Pre-installs Hatch build backends into the build-tree virtual environment used by the parent project.

Runtime and visualization fixes

• Reduced import-time cost by keeping heavy PyVista / Qt / plotting imports lazy where practical.
• Suppressed a noisy VTK warning in geometry-running workflows.

Supported platforms

• Linux
• macOS

Dependencies

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

Compatibility notes

• The dev GitHub release is a moving development snapshot and is not published to PyPI.
• PyPI publishing is intended for stable vX.Y.Z tags only.
• The custom GEMC Software License is provided through LICENSE.md; no OSI license classifier is declared.

v0.1.0

Initial release of pygemc — the Python API for GEMC geometry definition and output analysis.

Release notes

pygemc provides a pure-Python interface to define Geant4 detector geometries, materials, and
simulation configurations without writing C++ code. Output files produced by the gemc binary
can be read back and analysed entirely from Python.

Geometry API

• GVolume — define Geant4 solids, placements, sensitive detectors, and mirrors
• GMaterial — define materials by composition, density, and optical properties
• GConfiguration — configure and run a full geometry export (ASCII, SQLite)
• GColors — named color palette for volume visualization
• autogeometry — decorator that wires a geometry function into the gemc plugin system
• G4 unit converters: convert_length, convert_angle, convert_time, convert_energy, convert_list
• g4_units module with the complete Geant4 unit table
• PyVista-based 3D visualization (pyvista_api)
• SVG and HTML solid previews

Output formats

• ASCII flat-file geometry database
• SQLite geometry database

Analyzer

• GemcOutput — read and inspect gemc simulation output
• read_output — convenience loader for multiple output formats
• plot_variable — quick histogram/scatter plots from simulation data
• gemc-analyzer CLI entry point

CLI tools

• gemc-system-template — scaffold a new detector system from a Geant4 solid template

Tests

• test_cli.py — CLI smoke tests for all supported solid types
• test_geometry.py — geometry creation and database export for ASCII and SQLite formats

CI

• GitHub Actions workflow with automated install and test on push

Supported platforms

• Linux (amd64 and arm64)
• macOS

Dependencies

• Python 3.10 or higher
• numpy, pandas, matplotlib, pyyaml (installed automatically)
• vtk, pyvista, pyvistaqt, pyqt6 (visualization, installed at deploy time)