Composite MaskGroup of MaskGroup instances, representing the partons of the hard process and their descendants. Uses a tree structure, such that partons which are descendants of other hard partons are accessible, and nested within their parents.

Parameters:¶

graph : Graphicle¶

The event to be parsed. Must include status, edges, pmu, and pdg data.

desc : MaskGroup[MaskArray], optional¶

If the masks for all partons in the hard process have already been computed, these may be passed here to save performing the computation again.

Returns:¶

Nested composite of MaskGroup instances, representing the hierarchical structure of the hard process, and the descendants of the hard process partons throughout the shower. Nested MaskGroup instances additionally contain a latent MaskArray, referring to the parent parton and its descendants which are not also descendants of the children partons.

Return type:¶

MaskGroup[MaskGroup | MaskArray]

Examples

Generating an event and automatically detecting process structure:

>>> import showerpipe as shp
... import graphicle as gcl
...
... # generate event using showerpipe
... lhe_url = ("https://zenodo.org/record/6034610/"
...            "files/unweighted_events.lhe.gz")
... gen = shp.generator.PythiaGenerator(
...             "pythia-settings.cmnd", lhe_url)
... event = next(gen)
... # create graphicle objects
... graph = gcl.Graphicle.from_event(event)
... masks = gcl.select.hierarchy(graph)
...
>>> masks
MaskGroup(masks=["t", "t~"], agg_op=OR)
>>> masks["t"]
MaskGroup(masks=["b", "W+", "latent"], agg_op=OR)
>>> print(masks)  # view full nested structure
MaskGroup(agg_op=OR)
├── t
│   ├── b
│   ├── W+
│   │   ├── tau+
│   │   ├── nu(tau)
│   │   └── latent
│   └── latent
└── t~
    ├── b~
    ├── W-
    │   ├── s
    │   ├── c~
    │   └── latent
    └── latent
>>> # latent contains the mask not from constituents
... graph[masks["t"]["latent"]].pdg.name
array(['t', 't', 't', 't', 't'], dtype=object)

Notes

This function will not separate the mixed heritage when two sibling hard partons share ancestry for a given particle. In order to partition the resulting structure, use partition_descendants().