topology

import qrules.topology

Functionality for Topology and Transition instances.

Main interfaces

• Topology and its builder functions create_isobar_topologies() and create_n_body_topology().

• Transition and its two implementations MutableTransition and FrozenTransition.

class FrozenDict(*args, **kwargs)

Bases: frozendict, Generic[KT, VT]

A sortable version of frozendict.

class Edge(originating_node_id: int | None = None, ending_node_id: int | None = None)

Bases: object

Struct-like definition of an edge, used in Topology.edges.

originating_node_id: int | None

Node ID where the Edge starts.

An Edge is incoming to a Topology if its originating_node_id is None (see incoming_edge_ids).

ending_node_id: int | None

Node ID where the Edge ends.

An Edge is outgoing from a Topology if its ending_node_id is None (see outgoing_edge_ids).

get_connected_nodes() → set[int]

Get all node IDs to which the Edge is connected.

class Topology(nodes: Iterable[int], edges: Mapping[int, Edge])

Bases: object

Directed Feynman-like graph without edge or node properties.

A Topology is directed in the sense that its edges are ingoing and outgoing to specific nodes. This is to mimic Feynman graphs, which have a time axis. Note that a Topology is not strictly speaking a graph from graph theory, because it allows open edges, like a Feynman-diagram.

The edges and nodes can be provided with properties with a Transition, which contains a topology.

As opposed to a MutableTopology, a Topology is frozen, hashable, and ordered, so that it can be used as a kind of fingerprint for a Transition. In addition, the IDs of edges are guaranteed to be sequential integers and follow a specific pattern:

• incoming_edge_ids (initial_states) are always negative.

• outgoing_edge_ids (final_states) lie in the range 0...n-1 with n the number of final states.

• intermediate_edge_ids continue counting from n.

See also MutableTopology.organize_edge_ids().

Example

Isobar decay topologies can best be created as follows:

>>> topologies = create_isobar_topologies(number_of_final_states=3)
>>> len(topologies)
1
>>> topologies[0]
Topology(nodes=..., edges=...)

nodes: frozenset[int]

A node is a point where different edges connect.

edges: FrozenDict[int, Edge]

Mapping of edge IDs to their corresponding Edge definition.

incoming_edge_ids: frozenset[int]

Edge IDs of edges that have no originating_node_id.

Transition.initial_states provide properties for these edges.

outgoing_edge_ids: frozenset[int]

Edge IDs of edges that have no ending_node_id.

Transition.final_states provide properties for these edges.

intermediate_edge_ids: frozenset[int]

Edge IDs of edges that connect two nodes.

is_isomorphic(other: Topology) → bool

Check if two graphs are isomorphic.

Returns True if the two graphs have a one-to-one mapping of the node IDs and edge IDs.

Warning

Not yet implemented.

get_edge_ids_ingoing_to_node(node_id: int) → set[int]

get_edge_ids_outgoing_from_node(node_id: int) → set[int]

get_originating_final_state_edge_ids(node_id: int) → set[int]

get_originating_initial_state_edge_ids(node_id: int) → set[int]

relabel_edges(old_to_new: Mapping[int, int]) → Topology

Create a new Topology with new edge IDs.

This method is particularly useful when creating permutations of a Topology, e.g.:

>>> topologies = create_isobar_topologies(3)
>>> len(topologies)
1
>>> topology = topologies[0]
>>> final_state_ids = topology.outgoing_edge_ids
>>> permuted_topologies = {
...     topology.relabel_edges(dict(zip(final_state_ids, permutation)))
...     for permutation in itertools.permutations(final_state_ids)
... }
>>> len(permuted_topologies)
3

swap_edges(edge_id1: int, edge_id2: int) → Topology

get_originating_node_list(topology: Topology, edge_ids: Iterable[int]) → list[int]

Get list of node ids from which the supplied edges originate from.

Parameters:

• topology – The Topology on which to perform the search.

• edge_ids ([int]) – A list of edge ids for which the origin node is searched for.

class MutableTopology(nodes: Iterable[int] = NOTHING, edges: Mapping[int, Edge] = NOTHING)

Bases: object

Mutable version of a Topology.

A MutableTopology can be used to conveniently build up a Topology (see e.g. SimpleStateTransitionTopologyBuilder). It does not have restrictions on the numbering of edge and node IDs.

nodes: set[int]

See Topology.nodes.

edges: dict[int, Edge]

See Topology.edges.

add_node(node_id: int) → None

Adds a node with number node_id.

Raises:

ValueError – if node_id already exists in nodes.

add_edges(edge_ids: Iterable[int]) → None

Add edges with the ids in the edge_ids list.

Raises:

ValueError – if edge_ids already exist in edges.

attach_edges_to_node_ingoing(ingoing_edge_ids: Iterable[int], node_id: int) → None

Attach existing edges to nodes.

So that the are ingoing to these nodes.

Parameters:

• ingoing_edge_ids ([int]) – list of edge ids, that will be attached

• node_id (int) – id of the node to which the edges will be attached

Raises:

• ValueError – if an edge not doesn’t exist.

• ValueError – if an edge ID is already an ingoing node.

attach_edges_to_node_outgoing(outgoing_edge_ids: Iterable[int], node_id: int) → None

organize_edge_ids() → MutableTopology

Organize edge IDS so that they lie in range [-m, n+i].

Here, m is the number of incoming_edge_ids, n is the number of outgoing_edge_ids, and i is the number of intermediate_edge_ids.

In other words, relabel the edges so that:

• incoming edge IDs lie in the range [-1, -2, ...],

• outgoing edge IDs lie in the range [0, 1, ..., n],

• intermediate edge IDs lie in the range [n+1, n+2, ...].

freeze() → Topology

Create an immutable Topology from this MutableTopology.

You may need to call organize_edge_ids() first.

class InteractionNode(number_of_ingoing_edges: int, number_of_outgoing_edges: int)

Bases: object

Helper class for the SimpleStateTransitionTopologyBuilder.

number_of_ingoing_edges: int

number_of_outgoing_edges: int

class SimpleStateTransitionTopologyBuilder(interaction_node_set: Iterable[InteractionNode])

Bases: object

Simple topology builder.

Recursively tries to add the interaction nodes to available open end edges/lines in all combinations until the number of open end lines matches the final state lines.

interaction_node_set: list[InteractionNode]

build(number_of_initial_edges: int, number_of_final_edges: int) → tuple[Topology, ...]

create_isobar_topologies(number_of_final_states: int) → tuple[Topology, ...]

Builder function to create a set of unique isobar decay topologies.

Parameters:

number_of_final_states – The number of outgoing_edge_ids (final_states).

Returns:

A sorted tuple of non-isomorphic Topology instances, all with the same number of final states.

Example

>>> topologies = create_isobar_topologies(number_of_final_states=4)
>>> len(topologies)
2
>>> len(topologies[0].outgoing_edge_ids)
4
>>> len(set(topologies))  # hashable
2
>>> list(topologies) == sorted(topologies)  # ordered
True

create_n_body_topology(number_of_initial_states: int, number_of_final_states: int) → Topology

Create a Topology that connects all edges through a single node.

These types of “\(n\)-body topologies” are particularly important for check_reaction_violations() and conservation_rules.

Parameters:

• number_of_initial_states – The number of incoming_edge_ids (initial_states).

• number_of_final_states – The number of outgoing_edge_ids (final_states).

Example

>>> topology = create_n_body_topology(
...     number_of_initial_states=2,
...     number_of_final_states=5,
... )
>>> topology
Topology(nodes=..., edges...)
>>> len(topology.nodes)
1
>>> len(topology.incoming_edge_ids)
2
>>> len(topology.outgoing_edge_ids)
5

class Transition

Bases: ABC, Generic[EdgeType, NodeType]

Mapping of edge and node properties over a Topology.

This interface class describes a transition from an initial state to a final state by providing a mapping of properties over the edges and nodes of its topology. Since a Topology behaves like a Feynman graph, edges are considered as “states” and nodes are considered as interactions between those states.

There are two implementation classes:

• FrozenTransition: a complete, hashable and ordered mapping of properties over the edges and nodes in its topology.

• MutableTransition: comparable to MutableTopology in that it is used internally when finding solutions through the StateTransitionManager etc.

These classes are also provided with mixin attributes initial_states, final_states, intermediate_states, and filter_states().

abstract property topology: Topology

Topology over which states and interactions are defined.

abstract property states: Mapping[int, EdgeType]

Mapping of properties over its topology edges.

abstract property interactions: Mapping[int, NodeType]

Mapping of properties over its topology nodes.

property initial_states: dict[int, EdgeType]

Properties for the incoming_edge_ids.

property final_states: dict[int, EdgeType]

Properties for the outgoing_edge_ids.

property intermediate_states: dict[int, EdgeType]

Properties for the intermediate edges (connecting two nodes).

filter_states(edge_ids: Iterable[int]) → dict[int, EdgeType]

Filter states by a selection of edge_ids.

class FrozenTransition(topology: Topology, states, interactions)

Bases: Transition, Generic[EdgeType, NodeType]

Defines a frozen mapping of edge and node properties on a Topology.

topology: Topology

states: FrozenDict[int, EdgeType]

interactions: FrozenDict[int, NodeType]

unfreeze() → MutableTransition[EdgeType, NodeType]

Convert into a MutableTransition.

convert() → FrozenTransition[EdgeType, NodeType]

convert(state_converter: Callable[[EdgeType], NewEdgeType]) → FrozenTransition[NewEdgeType, NodeType]

convert(*, interaction_converter: Callable[[NodeType], NewNodeType]) → FrozenTransition[EdgeType, NewNodeType]

convert(state_converter: Callable[[EdgeType], NewEdgeType], interaction_converter: Callable[[NodeType], NewNodeType]) → FrozenTransition[NewEdgeType, NewNodeType]

Cast the edge and/or node properties to another type.

class MutableTransition(topology: Topology, states: Mapping[int, EdgeType] = NOTHING, interactions: Mapping[int, NodeType] = NOTHING)

Bases: Transition, Generic[EdgeType, NodeType]

Mutable implementation of a Transition.

Mainly used internally by the StateTransitionManager to build solutions.

topology: Topology

states: dict[int, EdgeType]

interactions: dict[int, NodeType]

compare(other: MutableTransition, state_comparator: Callable[[EdgeType, EdgeType], bool] | None = None, interaction_comparator: Callable[[NodeType, NodeType], bool] | None = None) → bool

swap_edges(edge_id1: int, edge_id2: int) → None

freeze() → FrozenTransition[EdgeType, NodeType]

Convert into a FrozenTransition.