decomposition package

Submodules

decomposition.decomposer module

decomposition.decomposer.build_subtree_cacheFor(particleID: int, decayDict: Dict[int, List[decayTuple]], particleOrderDict: Dict[int, int], memo: Optional[Dict[int, Tuple[subtreeTuple, ...]]] = None, visiting: Optional[Set[int]] = None, minBR: float = 0.0, sort: bool = True) → Dict[int, Tuple[subtreeTuple, ...]]

Build memoized subtree tuples for all descendants of particleID.

Parameters

sort – If False, do not sort the subtrees generated for particleID. However, all the other subtrees generated for the descendants of particleID will always be sorted.

decomposition.decomposer.decayTupleObj

alias of decayTuple

decomposition.decomposer.decompose(model: Model, sigmacut: Union[float, int, Unum] = 0.00E+00[fb], massCompress: bool = True, invisibleCompress: bool = True, minmassgap: Unum = 0.00E+00[GeV], minmassgapISR: Unum = 0.00E+00[GeV]) → TopologyDict

Decompose a BSM model into a list of SMS topologies.

Parameters

• model – Model object containing the BSM and SM particles and their decays

• sigmacut – minimum cross-section to be included in the decomposition

• massCompress – if True, perform mass compression

• invisibleCompress – if True, perform invisible compression

• minmassgap – minimum mass difference (in GeV) for mass compression

• minmassgapISR – minimum mass difference (in GeV) for pure ISR compression

Returns

TopologyDict containing the decomposed SMS topologies

decomposition.decomposer.get_lightweight_canonName(sorted_subtrees: List[subtreeTuple]) → int

Get a canonical name for a subtree based on the canonNames of its daughter subtrees. The canonName is constructed as ‘1’ + concatenation of sorted daughter canonNames + ‘0’. The subtrees are assumed to be already sorted by canonName and particle ordering, so that the same physical subtree will always have the same canonName regardless of the order in which the daughters were combined.

decomposition.decomposer.get_lightweight_decays(model: Model, particleOrderDict: Dict[int, int]) → Dict[int, List[decayTuple]]

Build a lightweight decay representation for all particles in the model, keyed by particle hash. The daughters in a given decay are sorted by their order from particleOrderDict to ensure consistent ordering when building subtrees.

decomposition.decomposer.get_lightweight_xsecs(model: Model, sigmacutFB: float) → List[xsecTuple]

Build a lightweight cross-section representation for all particle pairs in the model. The primary mothers in a given production channel are sorted by their order from particleOrderDict to ensure consistent ordering when building subtrees.

decomposition.decomposer.get_particle_order_dict(model: Model) → Dict[int, int]

Get a dictionary mapping particle hash to an integer representing the order of the particle in the model. This is used for sorting leaves and trees.

decomposition.decomposer.lightweight_sortParticleIDs(particleIDs: List[int], particleOrderDict: Dict[int, int]) → List[int]

Sort a list of particle IDs based on their order in the model.

decomposition.decomposer.lightweight_sortTrees(subtreeList: Iterable[subtreeTuple], particleOrderDict: Dict[int, int]) → List[subtreeTuple]

Sort a list of subtree tuples first by canonName, then by order of the particles appearing in it. It assumes the sub-subtrees are arleady sorted by the same criteria.

decomposition.decomposer.simplify_bsm_particles(model: Model) → Dict[int, Union[MultiParticle, Particle]]

Simplify BSM particles by merging particles which can be considered as equal. These particles should be used to replaced the original particles in the SMS topologies and reduce the number of physically equivalent SMS generated during decomposition.

class decomposition.decomposer.subtreeTuple(particleIDs, edges, decayBRs, canonName)

Bases: tuple

Create new instance of subtreeTuple(particleIDs, edges, decayBRs, canonName)

canonName

Alias for field number 3

decayBRs

Alias for field number 2

edges

Alias for field number 1

particleIDs

Alias for field number 0

decomposition.decomposer.xsecTupleObj

alias of xsecTuple

decomposition.exceptions module

exception decomposition.exceptions.SModelSDecompositionError(value: Optional[str] = None)

Bases: Exception

Class to define SModelS specific errors

decomposition.theorySMS module

class decomposition.theorySMS.TheorySMS

Bases: GenericSMS

A class for describing Simplified Model Topologies generated by the decompostion of full BSM models.

Initialize basic attributes.

addNodesFrom(other: TheorySMS)

Combines the nodes (add particles) in equivalent nodes in each trees. Can only be done if the trees have the same topology and ordering.

Parameters

other – TheorySMS object

attachDecay(motherIndex: int, decayNodes: list, br: float = 1.0, copy: bool = True) → TheorySMS

Attaches a decay to self. If copy = True, returns a copy of self with the decay attached.

Parameters

• motherIndex – Node index for the mother to which the decay should be added.

• decayNodes – Particle nodes for the daughters.

• br – Branching ratio value for the decay

• copy – if True, return a copy of self, with the decay attached.

Returns

new tree with the other composed with self.

compareTo(other: TheorySMS) → int

Compare self to other. If the SMS are not sorted, sort them and then do a direct comparison of each node with the same nodeIndex.

Parameters

other – SMS object to be compared against self

Returns

0, if objects are equal, -1 if self < other, 1 if self > other

compress(doCompress: bool, doInvisible: bool, minmassgap: Unum, minmassgapISR: Unum) → List[TheorySMS]

Keep compressing the original SMS and the derived ones till they can be compressed no more.

Parameters

• doCompress – if True, perform mass compression

• doInvisible – if True, perform invisible compression

• minmassgap – value (in GeV) of the maximum mass difference for compression (if mass difference < minmassgap, perform mass compression)

• minmassgapISR – value (in GeV) for mass compression leading to pure ISR signature, i.e. PV > MET + MET + … MET, (if all mass differences < minmassgapISR allow a pure ISR SMS)

Returns

list with the compressed SMS (TheorySMS objects)

computeWeightList() → Optional[Any]

Computes the SMS weight (production cross-section*BRs) using maxWeight and the production cross-section.

Returns

CrossSectionList object

copy(emptyNodes: bool = False) → TheorySMS

Returns a shallow copy of self.

Parameters

emptyNodes – If True, does not copy any of the nodes from self.

Returns

TheorySMS object

classmethod from_treeTuple(tree: Any, particleDict: Dict[int, Particle], sort: bool = True) → TheorySMS

Create a TheorySMS object from a named subtree tuple.

Parameters

• treetuple – treetuple describing the SMS topology and particles

• particleDict – dictionary mapping particle IDs to particle objects

Returns

TheorySMS object

getAncestors() → List[TheorySMS]

Get a list of all the ancestors of self. The list is ordered so the mothers appear first, then the grandmother, then the grandgrandmothers,…

Returns

A list of SMS objects containing all the ancestors sorted by generation.

invisibleCompress() → Optional[TheorySMS]

Perform invisible compression. It is done if there is a decay of the type BSM > xxx if all daughters are leaves and can be considered MET and the mother can be considered MET OR decays promptly.

Returns

compressed copy of the SMS, if element ends with invisible particles; None, if compression is not possible

isRelatedTo(other: TheorySMS) → bool

Checks if self has other as an ancestor or they share ancestors. Returns True if self and other have at least one ancestor in common, otherwise returns False.

Returns

True/False

massCompress(minmassgap: Unum, minmassgapISR: Unum) → Optional[TheorySMS]

Perform mass compression. It is only done if there is one decay of type BSM_i -> BSM_j + (any number of SM), where mass(BSM_i) - mass(BSM_j) < minmassgap AND BSM_i have a prompt decay.

Parameters

• minmassgap – value (in GeV) of the maximum mass difference for compression (if mass difference < minmassgap -> perform mass compression)

• minmassgapISR – value (in GeV) for mass compression leading to pure ISR signature, i.e. PV > MET + MET + … MET, (if all mass differences < minmassgapISR allow a pure ISR SMS)

Returns

compressed copy of self, if two masses in the SMS can be considered degenerate; None, if compression is not possible;

setAncestors(keepIDs: Union[None, List[int]] = None)

Set the list of ancestors for self, keeping only the SMS which have IDs in the keepIDs list.

Parameters

keepIDs – List of SMS IDs to be kept as ancestors.

setCoveredBy(resultType: str)

Tag the sms as covered by the result type (it is tested AND its parameters are within the result grid). It also recursively tags all of its ancestors.

Parameters

resultType – String describing the type of result (e.g. ‘prompt’, ‘displaced’)

setGlobalProperties(sort: bool = True, canonName: bool = True, weight: bool = True)

Compute and set global properties for the SMS (sort, renumber nodes, compute the canonical name and its total weight). Should only be called once the SMS will no longer be modified.

Parameters

• canonName – If True, compute its canonical name

• sort – If True, sort the SMS

• weight – If True, compute its total weight

setTestedBy(resultType: str)

Tag the sms as tested by the result type. It also recursively tags all of its ancestors.

Parameters

resultType – String describing the type of result (e.g. ‘prompt’, ‘displaced’)

decomposition.topologyDict module

class decomposition.topologyDict.TopologyDict

Bases: OrderedDict

An instance of this class represents an iterable collection of topologies.

addSMS(newSMS: TheorySMS) → bool

Add a new SMS to the dictionary. If an SMS with the same canonical name and topology already exists, merge them.

Parameters

newSMS – TheorySMS object to be added

Returns

True if the SMS was added, False otherwise

compress(doCompress: bool, doInvisible: bool, minmassgap: Unum, minmassgapISR: Unum)

Compress all SMS in the dictionary and include the compressed SMS in the topology list.

Parameters

• doCompress – if True, perform mass compression

• doInvisible – if True, perform invisible compression

• minmassgap – value (in GeV) of the maximum mass difference for compression (if mass difference < minmassgap, perform mass compression)

• minmassgapISR – value (in GeV) for mass compression leading to pure ISR signature, i.e. PV > MET + MET + … MET, (if all mass differences < minmassgapISR allow a pure ISR SMS)

getSMSList(canonName: Optional[int] = None) → List[TheorySMS]

Return a list with all the SMS appearing in the dict. If canonName is not None, return the SMS with the corresponding canonical name only.

Parameters

canonName – if None, return all SMS, otherwise return only the the SMS with the corresponding canonical name.

Returns

List of TheorySMS objects.

getTotalWeight(canonName: Optional[int] = None) → Any

Compute the summed cross-section over all the SMS. If canonName is not None, return the total cross-section for the SMS with the corresponding canonName.

numberOfSMS(canonName: Optional[int] = None) → int

Return the number of SMS in the dict. If canonName is not None, return the number of SMS with the corresponding canonName.

Parameters

canonName – if None, return the total number of SMS, otherwise return only the number of SMS with the corresponding canonical name.

Returns

Number of SMS in the dict.

setSMSAncestors()

Set the list of ancestors for each SMS in the Topology list keeping only the SMS which belongs to self (remove intermediate ancestors).

setSMSIds()

Assign unique ID to each SMS in the Topology list

sort()

Sort the dictionary keys and store it in a new ordered dict in self.

Module contents