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 compute the operation.
• The GEMC home PyVista API page documents variation selection, large-scene batching, and summary-log
  behavior.
• The README and GEMC home analyzer page document required true-information columns, PID matching,
  residual definitions, delta_phi wrapping, and CLI and Python PID-filter examples.
• The README lists gemc-cure-mesh, and the GEMC home API documentation includes a Cure Mesh page.
• geometry_source/htcc/cad/cad__default.yaml provides the YAML equivalent of cad_default.gxml and can
  be uploaded with gemc-sqlite -cad cad__default.yaml.
• The examples/basic/cad example imports heart, lung, and liver STL meshes as dosimeter volumes under
  a gamma source. Its YAML defines organ scale, position, color, and tissue material, and its meshes are
  prepared with gemc-cure-mesh.
• Analyzer tests cover original-track residuals, wrapped delta_phi, incomplete CSV input, API and CLI
  PID filtering, y-vs-x filtering, and empty-selection handling.
• Analyzer CLI tests cover filename-only summaries and event counts, explicit --list, stream inference
  for histograms and y-vs-x plots, and missing-variable diagnostics.
• test_gcad.py covers YAML and JSON loading, authoritative uploads, field aliases, and the missing
  system error.
• PyVista fake-renderer tests cover CAD STL path resolution, scaling, placement, and authored display
  attributes.