pythiaplotter.graphers package¶

Submodules¶

pythiaplotter.graphers.converters module¶

Functions to do conversions between particle representations.

pythiaplotter.graphers.converters.construct_edges_from_nodes(graph)[source]¶

Convert each node (representing a NodeParticle) into a EdgeParticle, with vertex barcodes.

To do this, we have to ensure that a particle’s incoming & outgoing vertices are concistent with its children & parents. Thus we ask them first for a suitable vertex, and if none can be found, create a new vertex barcode.

Parameters:	graph (NetworkX.MultiDiGraph) –
Returns:
Return type:	list[EdgeParticle]
Raises:	`IndexError` – If there is more than one unique candidate in/out vertex barcode.

pythiaplotter.graphers.converters.duplication_needed(graph, parents, children)[source]¶

For a set of parent and child nodes in a graph, determine if any duplicate nodes are needed.

This can happen when a subgraph of parent and child nodes has some child nodes that do not have all the same parents, and therefore duplicate nodes would be required to split the subgraph into multiple graphs where all the children do have the same parents.

Example

For a graph with edges [(1, 3), (1, 4), (2, 4), (2, 5)], nodes 1 and 2 are the parents, and nodes 3, 4, 5 are the children. 3 and 5 have one parent each (1 and 2, repsectively), but 4 has 2 parents. This would cause us issues when inserting edges in lieu of nodes.

Parameters:	graph (NetworkX.MultiDiGraph) – parents (list[int]) – children (list[int]) –
Returns:
Return type:	bool

pythiaplotter.graphers.converters.edge_to_node(graph)[source]¶

Converts graph from edge to node representation.

Create a node for each particle edge
Add directed edges between all combinations of incoming & outgoing particles at a vertex

Since there is a 1:1 correspondence between the node and edge particles, we can use the assign_particles_nodes() function to do this, so long as we construct our NodeParticles correctly.

Parameters:	graph (NetworkX.MultiDiGraph) –
Returns:
Return type:	NetworkX.MultiDiGraph

pythiaplotter.graphers.converters.get_all_children(graph, parents)[source]¶

Get all unique child nodes of all specified parent nodes in a flattened list.

Parameters:	graph (NetworkX.MultiDiGraph) – parents (list[int]) –
Returns:	Child nodes
Return type:	list[int]

pythiaplotter.graphers.converters.get_all_parents(graph, children)[source]¶

Get all unique parents nodes of all specified children nodes in a flattened list.

Parameters:	graph (NetworkX.MultiDiGraph) – children (list[int]) –
Returns:	Parent nodes
Return type:	list[int]

pythiaplotter.graphers.converters.get_related_parents_children(graph, node)[source]¶

Returns nodes indices of all children and their parents related to a node.

This includes:

the children of the node
all other parents of those children
all of those childens parents
all of those parents children
...

recursviely until we are done. Thus we obtain all nodes in this generation or 1 later, which are connected without straying outside of those two generations (ignoring the directionality of edges for a moment)

Parameters:

graph (NetworkX.MultiDiGraph) – Graph to analyze
node (int) – Node to consider

Returns:

all_parents (list[int]) – All connected parents
all_children (list[int]) – All connected children

pythiaplotter.graphers.converters.insert_duplicate_nodes(graph)[source]¶

Create a copy of the graph with duplicate parent nodes inserted when child has non-common shared parentage.

This can happen when a subgraph of parent and child nodes has some child nodes that do not have all the same parents, and therefore duplicate nodes would be required to split the subgraph into multiple graphs where all the children do have the same parents.

Duplicate parents have the same Particle as the parent, but with a barcode starting 20xxxx.

Parameters:	graph (NetworkX.MultiDiGraph) – Graph to analyze
Returns:	Copy of input graph but with duplicate parent nodes added.
Return type:	NetworkX.MultiDiGraph

pythiaplotter.graphers.converters.node_to_edge(graph)[source]¶

Converts graph from node to edge representation.

This conversion is more comples, and there is not always a simple 1:1 correspondence. Briefly:

1) Determine if certain parent-child relationships require a duplicate parent node to be inserted inbetween.

2) Turn each node into a directed edge with outgoing and incoming vertices, ensuring that all particles incoming (parents) & outgoing (children) from the same vertex have the same vertex barcode.

Connect all edges together into a graph.

The last step is done by passing a list of EdgeParticle s to assign_particle_edges(), thereby avoiding duplication.

Parameters:	graph (NetworkX.MultiDiGraph) –
Returns:
Return type:	NetworkX.MultiDiGraph

pythiaplotter.graphers.edge_grapher module¶

Attaches particles to a NetworkX graph, when EDGES represent particles.

Note about convention:

A particle’s “out” node is the one from which it is outgoing. Similarly, its “in” node is the one into which it is incoming. e.g. a –>– b : a is the “out” node, b is the “in” node for this edge.

An “incoming edge” to a node is an edge whose destination node is the node in question. Similarly, an “outgoing edge” from a node is any edge whose source is the node in question. e.g. c —p->– d: here p is an incoming edge to node d, whilst it is also an outgoing edge for node c.

pythiaplotter.graphers.edge_grapher.assign_particles_edges(edge_particles)[source]¶

Attach particles to directed graph edges when EDGES represent particles.

The graph itself is a networkx MultiDiGraph: a directed graph, that can have multiple edges between 2 nodes. We distinguish these via the edge[‘barcode’] attribute, where the barcode value = particle barcode. We can use MultiDiGraph.edges(data=True) to correctly iterate over all edges.

Additionally marks particles as initial/final state as necessary, based on whether they have any parents/children, respectively.

Parameters:	edge_particles (list[EdgeParticle]) – The Particle in each EdgeParticle will be assigned to a graph edge, using the vertex information in the EdgeParticle object.
Returns:	Directed graph with particles assigned to edges, and nodes to represent relationships.
Return type:	NetworkX.MultiDiGraph

pythiaplotter.graphers.edge_grapher.remove_particle_edge(graph, edge)[source]¶

Remove a particle edge from the graph.

Rewires the other particles such that the nodes at either end of the edge essentially merge together into one: - any children of the edge, are now children of the edge’s parents - any incoming edges into the edge’s in node are now

incoming to the out node (ie where the parents are incoming to)

Parameters:	graph (NetworkX.MultiDiGraph) – edge ((int, int)) – Outgoing node, incoming node

pythiaplotter.graphers.edge_grapher.remove_redundant_edges(graph)[source]¶

Remove redundant particle edges from a graph.

A particle is redundant when: 1) > 0 ‘child’ particles (those outgoing from the particle’s incoming node - this ensures we don’t remove final-state particles) 2) 1 ‘parent’ particle with same PDGID (incoming into the particle’s outgoing node - also ensures we don’t remove initial-state particles) 3) 0 ‘sibling’ particles (those outgoing from the particle’s outgoing node) Note that NetworkX includes an edge as its own sibling, so actually we require len(sibling_edges) == 1

e.g.:

--q-->-g->-g->-g->--u---->
    |             |
--q->             --ubar->

Remove the middle gluon and last gluon, since they add no information.

These redundants are useful to keep if considering MC internal workings, but otherwise are just confusing and a waste of space.

Since it loops over the list of graph edges, we can only remove one edge in a loop, otherwise adding extra/replacement edges ruins the sibling counting and doesn’t remove redundants. So the method loops through the graph edges until there are no more redundant edges.

Since we are dealing with MultiDiGraph, we have to be careful about siblings that actually span the same set of nodes - these shouldn’t be removed.

There is probably a more sensible way to do this, currently brute force and slow.

Parameters:	graph (NetworkX.MultiDiGraph) – Graph to remove redundant nodes from.

pythiaplotter.graphers.node_grapher module¶

Attaches particles to a NetworkX graph, when NODES represent particles.

pythiaplotter.graphers.node_grapher.assign_particles_nodes(node_particles)[source]¶

Attach Particles to a directed graph when NODES represent particles via NodeParticles.

NodeParticle objects must have their parent_barcodes specified for this to work.

It automatically attaches directed edges, between parent and child nodes.

Parameters:	node_particles (list[NodeParticle]) – List of NodeParticles, whose Particle’s will be attached to a graph with the relationship specified by self.parent_barcodes.
Returns:	Directed graph with particles assigned to nodes, and edges to represent relationships.
Return type:	NetworkX.MultiDiGraph

pythiaplotter.graphers.node_grapher.remove_isolated_nodes(gr)[source]¶

Remove nodes with no parents and no children.

Parameters:	gr (NetworkX.MultiDiGraph) –

pythiaplotter.graphers.node_grapher.remove_particle_node(graph, node)[source]¶: Remove a particle node from the graph

pythiaplotter.graphers.node_grapher.remove_redundant_nodes(graph)[source]¶

Remove redundant particle nodes from a graph.

i.e. when you have a particles which has 1 parent who has the same PDGID, and 1 child (no PDGID requirement).

e.g.:

->-g->-g->-g->-

These are useful to keep if considering Pythia8 internal workings, but otherwise are just confusing and a waste of space.

Parameters:	graph (NetworkX.MultiDiGraph) – Graph to remove redundant nodes from

Module contents¶

Functions to assign particles to a graph, and converting between node & edge representations.

pythiaplotter.graphers.assign_particles_to_graph(particles, default_repr, desired_repr=None, remove_redundants=True)[source]¶

Wrapper to easily assign particles to graph, change representation, remove redundants.

Parameters:	particles (list[NodeParticle], list[EdgeParticle]) – List of particles to be assigned to a graph. Must include relationship information. default_repr ({"NODE", "EDGE"}) – Particle representation for particles desired_repr ({"NODE", "EDGE"}, optional) – Desired output representation. remove_redundants (bool, optional) – Whether to remove redundant particles from the graph.
Returns:
Return type:	NetworkX.MultiDiGraph