Dev Nightly

Commits on main since 2026-06-17

• 2026-08-21 9bda243 - added GVolume.publish_passive for passive G4 placements. have pyvista skips volumes that are boolean components (by Maurizio Ungaro)
• 2026-08-18 4f8c128 - Typed absence for optional scalar string configuration values (by Maurizio Ungaro)
• 2026-08-17 21cb4c8 - new ci triggers and readme explaining the workflow (by Maurizio Ungaro)
• 2026-08-13 bc7ec19 - SQLite and ASCII systems can contain native and CAD volumes together, removing the need for a separate cad entry (by Maurizio Ungaro)
• 2026-08-04 92ff9f5 - ready for 0.4 release (by Maurizio Ungaro)
• 2026-07-23 dd96770 - added utility to remove holes from stl files (by Maurizio Ungaro)
• 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.4.0

PYGEMC Release 0.4.0

This version includes:

• PyVista variation filtering and batched rendering for large geometries
• p, theta, and phi residual plots with per-particle filtering and simpler analyzer commands
• Single-file CAD authoring, scaling, and PyVista rendering (upcoming in the
  next release)
• CAD mesh repair and hole-removal utilities (upcoming in the next
  release)
• Optical-surface publishing with GMirror and broader solid support (upcoming
  in the next release)

Release notes

Analyzer

• The analyzer plots p, theta, and phi residuals from original-track information and supports
  per-particle selection through both the Python API and CLI.
• (upcoming in the next release) gemc-analyzer now infers common input
  and stream choices, making summaries, histograms, and y-vs-x plots simpler to request.

API

GConfiguration and PyVista

• PyVista renders one selected variation without changing published output, while
  GConfiguration.show() reports the variation and run information.
• Large PyVista scenes are automatically batched, with CLI controls for overriding the behavior.
• (upcoming in the next release) PyVista renders SQLite CAD volumes,
  boolean-operation volumes, G4Polyhedra, and G4EllipticalTube solids.

CAD and mesh utilities

• (upcoming in the next release) gemc-sqlite -cad uploads an
  authoritative YAML or JSON CAD definition, including optional per-volume scaling.
• (upcoming in the next release) gemc-cure-mesh prepares CAD meshes
  for Geant4, while gemc-remove-holes fills small drilled through-holes.

Geometry

• (upcoming in the next release) GMirror defines and publishes optical
  boundaries that volumes can reference by name.
• (upcoming in the next release) GVolume accepts boolean-operation
  definitions without requiring a primitive solid.

Documentation

• Updated the README and GEMC home documentation for the analyzer, PyVista, and CAD mesh utilities.

Examples

• Added YAML-based HTCC and basic dosimetry examples for the new CAD authoring workflow.

Tests

• Expanded analyzer, CAD loader, and PyVista rendering coverage for the new behavior.

Addressed issues

• Issue #2: [High] add_rotation() emits a multi-token rotation string the C++ parser silently drops
• Issue #3: [High] set_rotation() then add_rotation() raises AttributeError due to inconsistent rotations type
• Issue #4: [High] make_polycone() length check uses and instead of or, missing single-array mismatches
• Issue #5: [High] make_trap() passes an extra self to already-bound methods, raising TypeError
• Issue #6: [Medium] GConfiguration ignores constructor args; argparse defaults clobber factory/variation/runno
• Issue #7: [Medium] gemc-sqlite CLI builds queries via raw f-strings (breakage + SQL injection)
• Issue #8: [Low] convert_angle(out='gon') returns radians instead of gradians
• Issue #15: Simplify Analyzer UI
• Issue #16: Plot smeared quantities

Supported platforms

• Linux
• macOS

Dependencies

• Python 3.10 or higher
• numpy, pandas, matplotlib
• pymeshlab for the gemc-cure-mesh CAD-mesh repair utility
• uproot and awkward for optional ROOT-file analysis via the root extra

Compatibility notes

Detailed list of changes and fixes

• GEMC's save_original_track option now provides otid, opid, opx, opy, and opz in
  true-information output for use as the original-track reference.
• The analyzer derives delta_p, delta_theta, and wrapped delta_phi for hits whose pid matches
  opid, using the hit value minus the original-track value.
• Per-particle plotting is available through the Python API pid argument and the CLI --pid <PDG ID>
  option, for example gemc-analyzer b2_t0_true_info.csv delta_p --data true_info --pid 2212. Empty
  selections exit normally with a concise message instead of a traceback.
• gemc-analyzer retains --kind as a hidden compatibility override, infers file types from extensions,
  and reports event counts in file summaries.
• Analyzer histogram and y-vs-x variables can be found across loaded streams without --data in common
  single-file workflows. --list explicitly requests a summary, and missing-variable errors list the
  available variables by stream.
• -pv, -pvb, and -pvvtk render the first published variation by default;
  --pyvista-variation NAME selects another variation without changing SQLite or ASCII output.
• GConfiguration.show() displays a variation/run table for multiple variations, records the run at
  each variation's publish time, and reports the selected PyVista variation.
• --pyvista-fast, --no-pyvista-fast, and --pyvista-fast-threshold N control large-scene batching.
  Actor creation is deferred until display or export time, and scenes above the threshold are batched
  automatically.
• gemc-sqlite -cad <file> writes YAML or JSON CAD definitions to the geometry table as solid="CAD"
  volumes whose mesh paths are stored in description.
• The CAD definition is authoritative: unlisted mesh files are not uploaded. Top-level defaults are
  overridden per volume, while sensitivity and identifiers are accepted as aliases for
  digitization and identifier.
• The YAML/JSON CAD workflow replaces the clas12Tags cad_<variation>.gxml mechanism.
• The Publish PyPI workflow can now be triggered by a published GitHub release and uses that release's
  tag to build and publish the package. Stable releases always publish to PyPI, while pre-releases are
  skipped; the existing manual workflow_dispatch with the TestPyPI option is unchanged.
• gemc-sqlite now binds user-supplied filter values as SQLite parameters and validates -what column
  names against the selected table schema before building a query.
• gcad.py accepts an optional scale key per CAD volume and stores it in the geometry parameters
  column; the GEMC CAD builder (buildSolid.cc) reads it and applies SetScale(CLHEP::mm * scale).
• pyvista_api.py now handles solid="CAD" volumes by reading the STL from description, resolving
  relative mesh paths against the SQLite database location, applying the CAD scale, and then using the
  existing PyVista render-entry pipeline for placement and display attributes.
• Added the pygemc.utilities package with cure_mesh(), registered the gemc-cure-mesh console-script
  entry point in pyproject.toml, and declared pymeshlab as a dependency.
• cure_mesh() welds coincident vertices, drops tiny disconnected components, reduces the target facet
  count through quadric edge collapse, repairs non-manifold edges, closes holes, and reorients facets
  coherently and outward. It accepts formats supported by pymeshlab, including STL, PLY, and OBJ, and
  prevents common hole, orientation, and negative-volume warnings from tessellated solids.
• Added remove_holes() to pygemc.utilities with the gemc-remove-holes console-script entry point.
  It handles drilled surface tunnels that cure_mesh() cannot close.
• remove_holes() classifies mesh facets perpendicular to each axis into shared-edge connected
  components and deletes small-diameter bolt tunnels. It then repairs and caps the openings, reducing
  the surface genus while preserving the bounding box and large apertures.
• GMirror requires type, finish, model, and border, where the border is SkinSurface or the
  name of a bordering volume.
• Mirror properties can come from a named matOptProps material or from tables evaluated at
  photonEnergy: indexOfRefraction, reflectivity, efficiency, specularlobe, specularspike,
  backscatter, and transmittance. sigmaAlpha specifies scalar roughness.
• GMirror.publish() writes <system>__mirrors_<variation>.txt for ASCII output or one SQLite
  mirrors row per mirror, keyed by experiment, system, variation, and run. It uses the same delete-once
  and duplicate-name guards as geometry and materials.
• GVolume.mirror references a mirror by name, replacing the GEMC2
  sensitivity: "mirror: <name>" overload.
• GVolume.check_validity() accepts a solidsOpr boolean-operation definition without also requiring a
  primitive solid and parameters, matching ported GEMC2 Operation: records.
• PyVista boolean meshes follow GEMC2 Operation: semantics, transforming the second operand by its
  position and inverse rotation.
• Boolean meshes use pymeshlab mesh-arrangement filters, fall back to VTK and then to the first operand,
  and are cached so repeated operations share a mesh.
• World transforms are resolved when rendering is flushed, allowing volumes to be published before
  their mothers. Component construction volumes remain available for boolean lookups but are not
  drawn.
• Pymeshlab boolean filters run in a worker subprocess to isolate its bundled Qt5 frameworks from the
  PyQt6 background plotter used by -pvb.
• Direct G4Box - G4Tubs and G4Box + G4Box paths preserve simple through-hole and orthogonal-cross
  cases when pymeshlab is unavailable and VTK cannot c...

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)