graphicle¶

The data structures and routines provided here enable the semantic storage, querying, and manipulation of data from high energy physics collision event records. This applies to both specific, homeogeneous data from the event record, eg. PDG codes, and to composite, heterogeneous objects comprising the whole record, eg. Graphicle objects.

The routines allow users to traverse ancestry using a topological directed cyclic graph (DAG) representation, select specific regions of the event, form clusters based on Monte-Carlo truth information, and perform calculations, such as the mass of said clusters.

HEP calculation routines¶

The following routines provide standard calculation utilities over particle physics data.

graphicle.calculate.weighted_centroid(...) → tuple[float, float][source]

Calculates the \(p_T\)-weighted centroid for a set of particles in the (pseudo)rapidity-azimuth plane.

graphicle.calculate.resultant_coords(...) → tuple[float, float][source]

Returns the resulting (pseudo)rapidity and azimuthal coordinates when summing the momenta of a particle set.

graphicle.calculate.combined_mass(pmu, ...) → float[source]

Returns the combined mass of the particles represented in the provided MomentumArray.

graphicle.calculate.cluster_coeff_distbn(...) → ndarray[Any, dtype[float32]][source]

A measure of clustering for a particle point-cloud. Transforms point-cloud into a graph, where node neighbourhood is determined by which particles fall within a distance on the \(\eta-\phi\) plane below radius. The clustering coefficients of these nodes are then computed.

graphicle.calculate.aggregate_momenta(pmu, ...) → MomentumArray[source]

Calculates the aggregate momenta for a sequence of clusters over the same point cloud of particles.

graphicle.calculate.thrust(pmu: MomentumArray, ...) → float[source]

graphicle.calculate.thrust(pmu: MomentumArray, return_axis) → float

graphicle.calculate.thrust(pmu: MomentumArray, rng_seed) → float

graphicle.calculate.thrust(pmu: MomentumArray) → float

graphicle.calculate.thrust(...) → tuple[float, ndarray[Any, dtype[float64]]]

graphicle.calculate.thrust(...) → tuple[float, ndarray[Any, dtype[float64]]]

Computes the thrust of an event, from the final-state momenta.

graphicle.calculate.spherocity(pmu: MomentumArray, ...) → float[source]

graphicle.calculate.spherocity(pmu: MomentumArray, ...) → float

graphicle.calculate.spherocity(pmu: MomentumArray, ...) → float

graphicle.calculate.spherocity(pmu: MomentumArray) → float

graphicle.calculate.spherocity(...) → tuple[float, ndarray[Any, dtype[float64]]]

graphicle.calculate.spherocity(...) → tuple[float, ndarray[Any, dtype[float64]]]

Computes the spherocity of an event, from final-state momenta.

graphicle.calculate.c_parameter(pmu: MomentumArray) → float[source]

Computes the C-parameter for the event, from the final state momenta.

graphicle.calculate.jaccard_distance(mask_1, ...) → float[source]

Computes the Jaccard distance between two sets.

Data structures¶

Data structures to semantically handle records for particle collision events. Interoperability with numpy API for non-composite objects is built-in.

class graphicle.data.AdjacencyList(graphicle.base.AdjacencyBase)[source]

Describes relations between particles in particle set using a COO edge list, and provides methods to convert representation.

class graphicle.data.ColorArray(graphicle.base.ArrayBase)[source]

Returns data structure of color / anti-color pairs for particle shower.

class graphicle.data.ColorElement(NamedTuple)[source]

Named tuple container for the color / anticolor pair of a single particle.

class graphicle.data.Graphicle[source]

Composite object, combining particle set data with relational information between particles.

class graphicle.data.HelicityArray(graphicle.base.ArrayBase)[source]

Data structure containing helicity / polarisation values for particle set.

class graphicle.data.MaskArray(graphicle.base.MaskBase, graphicle.base.ArrayBase)[source]

Boolean mask over Graphicle data structures.

class graphicle.data.MaskGroup(graphicle.base.MaskBase, MutableMapping[str, graphicle.data.MaskGeneric])[source]

Data structure to compose groups of masks over particle arrays. Can be nested to form complex hierarchies.

class graphicle.data.MomentumArray(graphicle.base.ArrayBase)[source]

Data structure containing four-momentum of particle list.

class graphicle.data.MomentumElement(NamedTuple)[source]

Named tuple container for the four-momentum of a single particle.

class graphicle.data.ParticleSet(graphicle.base.ParticleBase)[source]

Composite of data structures containing particle set description.

class graphicle.data.PdgArray(graphicle.base.ArrayBase)[source]

Returns data structure containing PDG integer codes for particle data.

class graphicle.data.StatusArray(graphicle.base.ArrayBase)[source]

Data structure containing status values for particle set.

class graphicle.data.VertexPair(NamedTuple)[source]

Named tuple container for the src and dst nodes representing an edge in a graph.

class graphicle.data.ParticleSetSerialized(TypedDict)[source]

Typed dictionary format of a serialized ParticleSet instance.

class graphicle.data.GraphicleSerialized(TypedDict)[source]

Typed dictionary format of a serialized Graphicle instance.

Data transformation routines¶

Provides functions to alter the representation of particle physics data.

class graphicle.transform.SphericalAngle(NamedTuple)[source]

Pair of inclination and azimuthal angles, respectively.

class graphicle.transform.SphericalAxis(NamedTuple)[source]

Axis vector in 3D cartesian coordinates.

graphicle.transform.soft_hard_axis(momenta) → SphericalAngle[source]

Calculates the axis defined by the plane swept out between the hardest and softest particles in momenta.

graphicle.transform.rotation_matrix(...) → ndarray[Any, dtype[float64]][source]

Computes the matrix operator to rotate a 3D vector with respect to an arbitrary axis by a given angle.

graphicle.transform.split_momentum(momentum, ...) → MomentumArray[source]

Splits the momentum of the given particle into two momenta. Energy and 3-momentum is conserved. Hardness and collinearity of the split are determined by z and angle.

graphicle.transform.split_hardest(momenta, ...) → MomentumArray[source]

Splits the momentum of the hardest particle into two momenta. Energy and 3-momentum is conserved over the whole MomentumArray. Hardness and collinearity of the split are determined by function parameters.

Matrix creation routines¶

Functions to create matrices (mostly representing inter-particle relationships) from particle physics data.

graphicle.matrix.cut_adj(...) → ndarray[Any, dtype[float64]][source]

Produce a directed adjacency matrix with outward edges towards the neighbours within a cut range, determined from the input affinity matrix.

graphicle.matrix.knn_adj(...) → ndarray[Any, dtype[float64]][source]

Produce a directed adjacency matrix with outward edges towards the k nearest neighbours, determined from the input affinity matrix.

graphicle.matrix.fc_adj(...) → ndarray[Any, dtype[float64]][source]

Create a fully connected adjacency matrix.

graphicle.matrix.delta_R_aff(pmu) → ndarray[Any, dtype[float64]][source]

Returns the inter-particle Euclidean distances between particles internally within the given MomentumArray.

graphicle.matrix.parton_hadron_distance(...) → ndarray[Any, dtype[float64]][source]

Calculates pairwise transverse-momentum (pt) weighted distances between two sets of 4-momenta. The pt weighting is raised to the power given by pt_exp.

Dataset filtering / masking¶

Algorithms to query event record, providing masks which select specific regions of collision events.

graphicle.select.fastjet_clusters(pmu, ...) → list[MaskArray][source]

Clusters particles using the FastJet implementation of the generalised-kt algorithm.

graphicle.select.find_vertex(...) → ndarray[Any, dtype[int32]][source]

Locate vertices with the inward and outward particles of the passed pdg codes.

graphicle.select.vertex_descendants(adj, ...) → MaskArray[source]

Returns a MaskArray to select edges which descend from a given interaction vertex.

graphicle.select.hadron_vertices(adj, ...) → tuple[int, ...][source]

Locates the hadronisation vertices in the generation DAG.

graphicle.select.partition_descendants(...) → MaskGroup[MaskGeneric][source]

Partitions the final state descendants with mixed hard partonic heritage, by aligning them with their nearest ancestor.

graphicle.select.hard_descendants(...) → MaskGroup[MaskArray][source]

Returns a MaskGroup instance to select particle descendants of target hard partons (by PDG code).

graphicle.select.hierarchy(...) → MaskGroup[MaskArray | MaskGroup][source]

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.

graphicle.select.leaf_masks(mask_tree) → MaskGroup[MaskArray][source]

Find the leaves of the hard process, when organised into a hierarchical tree from hierarchy().

graphicle.select.any_overlap(masks) → bool[source]

Given a MaskGroup object, checks if any of the masks overlap with each other.

graphicle.select.centroid_prune(pmu, ...) → MaskArray[source]

For a given MomentumArray, calculate the distance every particle is from a centroid location, and return a MaskArray for all of the particles which are within a given radius. If centre is not provided, the transverse momentum weighted centroid will be used.

graphicle.select.color_singlets(...) → list[tuple[str, ...]][source]

Identifies groups of outgoing partons from the hard process which form color singlets.

graphicle.select.clusters(graph, ...) → MaskGroup[MaskArray][source]

Cluster and tag the final state particles in an event represented by a Graphicle object. These clusters are formed by considering the topology of the directed acyclic graph (DAG) generating the event, tracking descendants of hard partons, and the momenta of the hard partons compared against the final state particles.

graphicle.select.arg_closest(focus: MomentumArray, ...) → list[int][source]

Assigns four-momenta elements in candidate to the nearest four-momenta elements in focus. Elements in candidate are assigned to one element in focus only.

graphicle.select.monte_carlo_tag(...) → MaskGroup[MaskArray][source]

Assigns clusters to nearest Monte-Carlo truth partons in the hard process. Clusters are drawn from cluster_masks, until each each parton is assigned.

Exceptions and warnings¶

Custom classes indicating to users specific issues relating to the unique cross-over between high energy physics and graph algorithms.

exception graphicle.base.NumericalStabilityWarning(UserWarning)[source]

Raised when the result of a calculation may not be numerically stable.