HEP extension modules¶

The HEP libraries contribute Python bindings dynamically. In gcompose, the Python engine asks PythonPluginRegistry for each loaded library and creates its submodule below uLib. The bindings also become convenience names in the console/Recipe namespace.

# gcompose console or Recipe, after the matching plugin has loaded
import uLib

if hasattr(uLib, "Detectors"):
    print("Detector bindings available")
if hasattr(uLib, "MuonTomography"):
    print("Tomography bindings available")
if hasattr(uLib, "Geant"):
    print("Geant bindings available")

This is intentionally different from built-in Core and Math. The standalone uLib_python extension links only Core and Math, so a normal Python process must not assume uLib.Geant or another HEP module exists. A remote Client can still inspect and edit all classes registered by its server, even when they are unavailable as local pybind classes.

Detectors¶

The uLib.Detectors plugin holds reconstructed muon data, collections, and chamber geometry.

Export	What it represents	Example
`ClosestApproach`	closest points and distance between two tracks	`ca = Detectors.ClosestApproach(); ca.valid = True`
`MuonEventData`	shared read-only track/momentum interface	`event.GetMomentum()`
`MuonEvent`	constructible incoming/outgoing event data	`event = Detectors.MuonEvent()`
`MuonScatter`	reconstructed scattering event	`scatter.SetMomentum(3.0); scatter.GetPoca()`
`MuonScatterCollection`	owning collection and summary statistics	`collection.Add(scatter); len(collection)`
`DetectorChamber`	transformed detector chamber volume	`Detectors.DetectorChamber(Math.Vector3f([1, 1, 1]))`

# gcompose only: the Detectors module must be loaded.
from uLib import Detectors, Math

scatter = Detectors.MuonScatter()
scatter.SetMomentum(3.0)
print(scatter.IsComplete(), scatter.GetScatterAngle())

events = Detectors.MuonScatterCollection("reconstructed")
events.Add(scatter)
print(events.GetCount(), events.GetMeanScatterAngle())

chamber = Detectors.DetectorChamber(Math.Vector3f([100, 100, 20]))
plane = chamber.GetLocalPlane()

ClosestApproach exposes valid, point, pointOnFirst, pointOnSecond, distance, firstParameter, and secondParameter. A MuonScatterCollection additionally reports dropped/complete counts and mean scatter angle.

Muon tomography¶

The uLib.MuonTomography plugin provides the event wrapper and image-algorithm base classes.

Export	What it represents	Example
`MuonScatterEvent`	an Object wrapper around one `MuonScatter`	`wrapped = MuonTomography.MuonScatterEvent(scatter)`
`MuonTomographyAlgorithm`	abstract common base for tomography algorithms	`isinstance(poca, MuonTomography.MuonTomographyAlgorithm)`
`PocaImageAlgorithm`	image reconstruction using point of closest approach	`poca = MuonTomography.PocaImageAlgorithm()`
`RayLengthImageAlgorithm`	image reconstruction using ray lengths	`rays = MuonTomography.RayLengthImageAlgorithm()`

# gcompose only: the MuonTomography plugin must be loaded.
from uLib import Detectors, MuonTomography

scatter = Detectors.MuonScatter()
event = MuonTomography.MuonScatterEvent(scatter)
assert event.Get() is not None

poca = MuonTomography.PocaImageAlgorithm()
poca.run()                         # configure its ports/properties first in a real scene

For a live reconstruction pipeline, use a stream input and a DataBuffer as described in Streaming, rather than collecting every muon into a Python list first.

Geant¶

The uLib.Geant plugin exposes a deliberately focused set of Geant scene, geometry, source, probe, and event classes. The full Geant object catalogue remains available in the application through the scene factory and ctx.create().

Export	What it represents	Example
`Scene`	configured simulation scene and Algorithm	`scene.Initialize(); scene.run_simulation()`
`Solid`	abstract transformed Geant solid	returned as a base class
`BoxSolid`	constructible box solid	`solid = Geant.BoxSolid("absorber")`
`TessellatedSolid`	tessellated solid	`solid = Geant.TessellatedSolid()`
`EmitterPrimary`	abstract transformed primary source	returned as a base class
`SkyPlaneEmitterPrimary`	plane source for sky-like primaries	`emitter = Geant.SkyPlaneEmitterPrimary()`
`PlaneProbe`	transformed plane that observes events	`probe = Geant.PlaneProbe()`
`GeantEvent`	one simulation event	`event.GetEventID(); event.GetMomentum()`
`GeantEventCollection`	collection of simulation events	`events.GetNumberOfItems()`

# gcompose only: the Geant plugin must be loaded.
from uLib import Geant, Math

solid = Geant.BoxSolid("absorber")
solid.SetSize(Math.Vector3f([100.0, 50.0, 10.0]))
solid.SetOrigin(Math.Vector3f([-50.0, -25.0, -5.0]))

scene = Geant.Scene()
scene.Initialize()
# Configure scene properties, sources, and volumes before scene.run_simulation().

Scene is an Algorithm, so it also exposes the Core controls such as run(), start(), and auto_run. It must run on the thread that built the Geant scene; the gcompose stream integration handles a consumer-driven run by posting work back to that thread.

Use HEP objects in a scene¶

When the task is to build a saved gcompose scene, prefer the scene façade instead of holding an isolated pybind object:

# gcompose console or Recipe
scene = ctx.create("Scene", "simulation")
box = ctx.create("BoxSolid", "absorber")
box.Size = [100, 50, 10]

# Discover exact names contributed by the loaded build.
print(ctx.classes())

The exact registered class names are build- and plugin-dependent. The application catalogue returned by ctx.classes(), or the remote server's catalog command, is the source of truth for a live session.

Other libraries¶

There are no pybind registration translation units for separate Root or Vtk Python modules in the current build. Their functionality is accessible through scene objects, gcompose display properties, Recipes, and remote proxies where the corresponding library has been loaded. This page and Plugin documentation are the place to add a new explicit Python module when one is introduced.