theory package

Submodules

theory.auxiliaryFunctions module

theory.auxiliaryFunctions.addInclusives(massList, shapeArray)

Add entries corresponding to ‘*’ in shapeArray. If shapeArray contains entries = ‘*’, the corresponding entries in value will be added from the output.

Parameters

• massList – 1D array of floats. Its dimension should be equal to the number of non “*” items in shapeArray (e.g. [200.0,100.0])

• shapeArray – 1D array containing the data type and ‘*’. The values of data type are ignored (e.g. [float,’*’,float,’*’,’*’]).

Returns

original array with ‘*’ inserted at the correct entries.

theory.auxiliaryFunctions.addUnit(obj, unit)

Add unit to object. If the object is a nested list, adds the unit to all of its elements.

Parameters

• obj – Object without units (e.g. [[100,100.]])

• unit – Unit to be added to the object (Unum object, e.g. GeV)

Returns

Object with units (e.g. [[100*GeV,100*GeV]])

theory.auxiliaryFunctions.average(values, weights=None, nround=-1)

Compute the weighted average of a list of objects. All the objects must be of the same type. If all objects are equal returns the first entry of the list. Only the average of ints, floats and Unum objects or nested lists of these can be computed. If the average can not be computed returns None.

Parameters

• values – List of objects of the same type

• weights – Weights for computing the weighted average. If None it will assume unit weights.

• nround – If greater than zero and the returning attibute is numeric, will round it to this number of significant digits.

theory.auxiliaryFunctions.cGtr(weightA, weightB)

Define the auxiliary greater function.

Return a number between 0 and 1 depending on how much it is violated (0 = A > B, 1 = A << B).

Returns

XSectioList object with the values for each label.

theory.auxiliaryFunctions.cSim(*weights)

Define the auxiliar similar function.

Return the maximum relative difference between any element weights of the list, normalized to [0,1].

Returns

XSectionList object with the values for each label.

theory.auxiliaryFunctions.elementsInStr(instring, removeQuotes=True)

Parse instring and return a list of elements appearing in instring. instring can also be a list of strings.

Parameters

• instring – string containing elements (e.g. “[[[‘e+’]],[[‘e-‘]]]+[[[‘mu+’]],[[‘mu-‘]]]”)

• removeQuotes – If True, it will remove the quotes from the particle labels. Set to False, if one wants to run eval on the output.

Returns

list of elements appearing in instring in string format

theory.auxiliaryFunctions.flattenArray(objList)

Flatten any nested list to a 1D list.

Parameters

objList – Any list or nested list of objects (e.g. [[[(100.,1e-10),100.],1.],[[200.,200.],2.],..]

Returns

1D list (e.g. [100.,1e-10,100.,1.,200.,200.,2.,..])

theory.auxiliaryFunctions.getAttributesFrom(obj, skipIDs=[])

Loops over all attributes in the object and return a list of the attributes.

Parameters

• obj – Any object with a __dict__ attribute

• skipIDs – List of object ids. Any object which has its id on the list will be ignored (useful to avoid recursion).

Returns

List with unique attribute labels.

theory.auxiliaryFunctions.getValuesForObj(obj, attribute)

Loops over all attributes in the object and in its attributes and returns a list of values for the desired attribute:

Parameters

• obj – Any object with a __dict__ attribute

• attribute – String for the desired attribute

Returns

List with unique attribute values. If the attribute is not found, returns empty list.

theory.auxiliaryFunctions.index_bisect(inlist, el)

Return the index where to insert item el in inlist. inlist is assumed to be sorted and a comparison function (lt or cmp) must exist for el and the other elements of the list. If el already appears in the list, inlist.insert(el) will insert just before the leftmost el already there.

theory.auxiliaryFunctions.removeInclusives(massArray, shapeArray)

Remove all entries corresponding to ‘*’ in shapeArray. If shapeArray contains entries = ‘*’, the corresponding entries in value will be removed from the output.

Parameters

• massArray – Array to be formatted (e.g. [[200.,100.],[200.,100.]] or [[200.,’*’],’*’],0.4])

• shapeArray – Array with format info (e.g. [‘*’,[float,float]])

Returns

formatted array (e.g. [[200.,100.]] or [[200.]],0.4])

theory.auxiliaryFunctions.removeUnits(value, standardUnits)

Remove units from unum objects. Uses the units defined in physicsUnits.standard units to normalize the data.

Parameters

• value – Object containing units (e.g. [[100*GeV,100.*GeV],3.*pb])

• standardUnits – Unum unit or Array of unum units defined to normalize the data.

Returns

Object normalized to standard units (e.g. [[100,100],3000])

theory.auxiliaryFunctions.rescaleWidth(width)

The function that is applied to all widths to map it into a better variable for interpolation. It grows logarithmically from zero (for width=0.) to a large number (machine dependent) for width = infinity.

Parameters

width – Width value (in GeV) with or without units

Return x

Coordinate value (float)

theory.auxiliaryFunctions.reshapeList(objList, shapeArray)

Reshape a flat list according to the shape of shapeArray. The number of elements in shapeArray should equal the length of objList.

Parameters

• objList – 1D list of objects (e.g. [200,100,’*’,50,’*’])

• shapeArray – Nested array (e.g. [[float,float,’*’,float],’*’])

Returns

Array with elements from objList shaped according to shapeArray (e.g. [[200.,100.,’*’,50],’*’])

theory.auxiliaryFunctions.roundValue(value, nround=-1)

Round a value to nround significant digits. If the input value is not a float or Unum object, it is zero or infinity, nothing is done.

Parameters

nround – number of significant digits

Returns

rounded value

theory.auxiliaryFunctions.unscaleWidth(x)

Maps a coordinate value back to width (with GeV unit). The mapping is such that x=0->width=0 and x=very large -> width = inf.

Parameters

x – Coordinate value (float)

Return width

Width value (in GeV) with unit

theory.branch module

class theory.branch.Branch(info=None, finalState=None, intermediateState=None, model=None)

Bases: object

An instance of this class represents a branch. A branch-element can be constructed from a string (e.g., (‘[b,b],[W]’).

Initializes the branch. If info is defined, tries to generate the branch using it.

Parameters

• info – string describing the branch in bracket notation (e.g. [[e+],[jet]])

• finalState – final state label string for the branch (e.g. ‘MET’ or ‘HSCP’)

• intermediateState – list containing intermediate state labels (e.g. [‘gluino’,’C1+’])

• model – The model (Model object) to be used when converting particle labels to particle objects (only used if info, finalState or intermediateState != None).

copy()

Generate an independent copy of self. Faster than deepcopy.

Returns

Branch object

decayDaughter()

Generate a list of all new branches generated by the 1-step cascade decay of the current branch daughter. :returns: list of extended branches (Branch objects). Empty list if daughter is stable or if daughterID was not defined.

getAverage(attr)

Get the average value for a given attribute appearing in the odd particles of branch.

getInfo()

Get branch topology info from evenParticles.

Returns

dictionary containing vertices and number of final states information

getLength()

Returns the branch length (number of odd particles).

Returns

length of branch (number of odd particles)

removeVertex(iv)

Remove vertex iv. The “vertex-mother” in BSMparticles and (SM) particles in the vertex are removed from the branch. The vertex index corresponds to the BSM decay (iv = 0 will remove the first BSM particle,…)

Parameters

iv – Index of vertex in branch (int)

setInfo()

Defines the number of vertices (vertnumb) and number of even particles in each vertex (vertpats) properties, if they have not been defined yet.

class theory.branch.InclusiveBranch(finalState=None, intermediateState=None, model=None)

Bases: Branch

An inclusive branch class. It will return True when compared to any other branch object with the same final state. If intermediateState is defined, it will use all the odd (BSM) particles for comparison while neglecting even particles.

Parameters

• info – string describing the branch in bracket notation (e.g. [[e+],[jet]])

• finalState – final state label string for the branch (e.g. ‘MET’ or ‘HSCP’)

• intermediateState – list containing intermediate state labels (e.g. [‘gluino’,’C1+’])

• model – The model (Model object) to be used when converting particle labels to particle objects (only used if info, finalState or intermediateState != None).

decayDaughter()

Always return False.

getInfo()

Get branch topology info (inclusive list and int).

Returns

dictionary containing vertices and number of final states information

theory.branch.decayBranches(branchList, sigcut=0.0)

Decay all branches from branchList until all unstable intermediate states have decayed.

Parameters

• branchList – list of Branch() objects containing the initial mothers

• sigcut – minimum sigma*BR (in fb) to be generated, by default sigcut = 0. (all branches are kept)

Returns

list of branches (Branch objects)

theory.clusterTools module

class theory.clusterTools.AverageElement(elements=[])

Bases: Element

Represents an element or list of elements containing only the basic attributes required for clustering or computing efficiencies/upper limits. Its properties are given by the average properties of the elements it represents and its weight is given by the total weight of all elements.

Initializes the element. If info is defined, tries to generate the element using it.

Parameters

• info – string describing the element in bracket notation (e.g. [[[e+],[jet]],[[e-],[jet]]])

• finalState – list containing the final state labels for each branch (e.g. [‘MET’, ‘HSCP’] or [‘MET’,’MET’])

• intermediateState – nested list containing intermediate state labels for each branch (e.g. [[‘gluino’], [‘gluino’]])

• model – The model (Model object) to be used when converting particle labels to particle objects (only used if info, finalState or intermediateState != None).

contains(element)

Check if the average element contains the element

Parameters

element – Element object

Returns

True/False

getAverage(attribute, weighted=True, nround=5)

Compute the average value for the attribute using the elements in self.elements. If weighted = True, compute the weighted average using the elements weights.

Parameters

• attribute – Name of attribute to be averaged over (string)

• weighted – If True, uses the element weights to compute a weighted average

• nround – If greater than zero and the returning attibute is numeric, will round it to this number of significant digits.

Returns

Average value of attribute.

class theory.clusterTools.ElementCluster(elements=[], dataset=None, distanceMatrix=None)

Bases: object

An instance of this class represents a cluster of elements. This class is used to store the relevant information about a cluster of elements and to manipulate this information.

add(elements)

Add an element or list of elements.

Parameters

elements – Element object or list of elements

averageElement()

Computes the average element for the cluster. The average element is an empty element, but with its mass and width given by the average over the cluster elements.

Returns

Element object

copy()

Returns a copy of the index cluster (faster than deepcopy).

getDataType()

Checks to which type of data (efficiency map or upper limit) the cluster refers to. It uses the cluster.dataset attribute. If not defined, returns None :return: upperLimits or efficiencyMap (string)

getDistanceTo(element)

Return the maximum distance between any elements belonging to the cluster and element.

Parameters

element – Element object

Returns

maximum distance (float)

getTotalXSec()

Return the sum over the cross sections of all elements belonging to the cluster.

Returns

sum of weights of all the elements in the cluster (XSectionList object)

indices()

Return a list of element indices appearing in cluster

isConsistent(maxDist)

Checks if the cluster is consistent. Computes an average element in the cluster and checks if this average element belongs to the cluster according to the maximum allowed distance between cluster elements.

Returns

True/False if the cluster is/is not consistent.

remove(elements)

Remove an element or a list of element from the cluster.

Parameters

elements – Element object or list of elements

theory.clusterTools.clusterElements(elements, maxDist, dataset)

Cluster the original elements according to their distance in upper limit space.

Parameters

• elements – list of elements (Element objects)

• dataset – Dataset object to be used when computing distances in upper limit space

• maxDist – maximum distance for clustering two elements

Returns

list of clusters (ElementCluster objects)

theory.clusterTools.doCluster(elements, dataset, maxDist)

Cluster algorithm to cluster elements.

Parameters

• elements – list of all elements to be clustered

• dataset – Dataset object to be used when computing distances in upper limit space

• maxDist – maximum distance for clustering two elements

Returns

a list of ElementCluster objects containing the elements belonging to the cluster

theory.clusterTools.groupElements(elements, dataset)

Group elements into groups where the average element identical to all the elements in group. The groups contain all elements which share the same mass,width and upper limit and can be replaced by their average element when building clusters.

Parameters

• elements – list of all elements to be grouped

• dataset – Dataset object to be used when computing distances in upper limit space

Returns

a list of AverageElement objects which represents a group of elements with same mass, width and upper limit.

theory.clusterTools.relativeDistance(el1, el2, dataset)

Defines the relative distance between two elements according to their upper limit values. The distance is defined as d = 2*|ul1-ul2|/(ul1+ul2).

Parameters

• el1 – Element object

• el2 – Element object

Returns

relative distance

theory.crossSection module

class theory.crossSection.XSection

Bases: object

An instance of this class represents a cross section.

This class is used to store the information of a single cross section (value, particle ids, center of mass, order and label).

order = 0 (LO), 1 (NLO), 2 (NLL), or 3 (NNLL).

Initializes the object to store a cross section value. All initial info is set to None.

copy()

Generates an independent copy of self.

Faster than deepcopy.

niceStr()

Generates a more human readable string. The string format is: Sqrts: self.info.sqrts, Weight: self.value

property pid

class theory.crossSection.XSectionInfo(sqrts=None, order=None, label=None)

Bases: object

An instance of this class represents information regarding a cross section.

This class is used to store information of a cross section (center of mass, order and label).

Constructor. :param: sqrts center of mass energy, with unit :param: order perturbation order of xsec computation :param: label, a string that describes the xsec computation

copy()

Generate an independent copy of self.

Faster than deepcopy.

normalizeSqrts(sqrts)

class theory.crossSection.XSectionList(infoList=None)

Bases: object

An instance of this class represents a list of cross sections.

This class is used to store a list of cross sections. The list is sorted by cross section, highest cross section first.

If infoList is defined, create entries with zero cross sections according to infoList. infoList must be a list of XSectionInfo objects.

add(newxsec)

Append a XSection object to the list.

copy()

Generates an independent copy of itself. Faster than deepcopy.

delete(xSec)

Delete the cross section entry from the list.

getDictionary(groupBy='pids')

Convert the list of XSection objects to a nested dictionary.

First level keys are the particles IDs (if groupBy == pids) or labels (if groupBy == labels) and values are the cross section labels or particle IDs and the cross section value.

getInfo()

Get basic info about the cross sections appearing in the list (order, value and label).

Returns

list of XSectionInfo objects

getMaxXsec()

Get the maximum cross section value appearing in the list.

getMinXsec()

Get minimum cross section value appearing in the list.

getPIDpairs()

Get all particle ID pairs appearing in the list.

getPIDs()

Get all particle IDs appearing in the list.

getXsecsFor(item)

Return a list of XSection objects for item (label, pid, sqrts).

niceStr()

order()

Order the cross section in the list by their PDG pairs

removeDuplicates()

If there are two entries for the same process, center of mass energy and order, keep only one (the one with highest value).

removeLowerOrder()

Keep only the highest order cross section for each process in the list.

Remove order information and set default labels.

sort()

sort the xsecs by the values

theory.crossSection.getXsecFromLHEFile(lhefile, addEvents=True)

Obtain cross sections from input LHE file.

Parameters

• lhefile – LHE input file with unweighted MC events

• addEvents – if True, add cross sections with the same mothers, otherwise return the event weight for each pair of mothers

Returns

a XSectionList object

theory.crossSection.getXsecFromSLHAFile(slhafile, useXSecs=None, xsecUnit=1.00E+00[pb])

Obtain cross sections for pair production of R-odd particles from input SLHA file. The default unit for cross section is pb.

Parameters

• slhafile – SLHA input file with cross sections

• useXSecs – if defined enables the user to select cross sections to use. Must be a XSecInfoList object

• xsecUnit – cross section unit in the input file (must be a Unum unit)

Returns

a XSectionList object

theory.crossSection.orderToString(order, short=False, raise_error=False)

return the string that describes the perturbation order :param short: if true, return a short version of string :param raise_error: if true, raise exception if order is not know

theory.crossSection.stringToOrder(strng)

from a string describing the order return the perturbation order

theory.decomposer module

theory.decomposer.decompose(model, sigmacut=1.00E-01[fb], doCompress=True, doInvisible=True, minmassgap=0.00E+00[GeV])

Perform decomposition using the information stored in model.

Parameters

• sigmacut – minimum sigma*BR to be generated, by default sigmacut = 0.1 fb

• doCompress – turn mass compression on/off

• doInvisible – turn invisible compression on/off

• minmassgap – maximum value (in GeV) for considering two R-odd particles degenerate (only revelant for doCompress=True )

Returns

list of topologies (TopologyList object)

theory.element module

class theory.element.Element(info=None, finalState=None, intermediateState=None, model=None)

Bases: object

An instance of this class represents an element. This class possesses a pair of branches and the element weight (cross-section * BR).

Initializes the element. If info is defined, tries to generate the element using it.

Parameters

• info – string describing the element in bracket notation (e.g. [[[e+],[jet]],[[e-],[jet]]])

• finalState – list containing the final state labels for each branch (e.g. [‘MET’, ‘HSCP’] or [‘MET’,’MET’])

• intermediateState – nested list containing intermediate state labels for each branch (e.g. [[‘gluino’], [‘gluino’]])

• model – The model (Model object) to be used when converting particle labels to particle objects (only used if info, finalState or intermediateState != None).

checkConsistency()

Check if the particles defined in the element are consistent with the element info.

Returns

True if the element is consistent. Print error message and exits otherwise.

compressElement(doCompress, doInvisible, minmassgap)

Keep compressing the original element 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)

Returns

list with the compressed elements (Element objects)

copy()

Create a copy of self. Faster than deepcopy.

Returns

copy of element (Element object)

getAncestors()

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

Returns

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

getAverage(attr)

Get the average value for a given attribute appearing in the odd particles of the element branches.

getEinfo()

Get element topology info from branch topology info.

Returns

dictionary containing vertices and number of final states information

getFinalStates()

Get the array of final state (last BSM particle) particle objects in the element.

Returns

list of Particle objects

hasTopInList(elementList)

Check if the element topology matches any of the topologies in the element list.

Parameters

elementList – list of elements (Element objects)

Returns

True, if element topology has a match in the list, False otherwise.

invisibleCompress()

Perform invisible compression.

Returns

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

isRelatedTo(other)

Checks if the element has any common ancestors with other or one is an ancestor of the other. Returns True if self and other have at least one ancestor in common or are the same element, otherwise returns False.

Returns

True/False

massCompress(minmassgap)

Perform mass compression.

Parameters

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

Returns

compressed copy of the element, if two masses in this element are degenerate; None, if compression is not possible;

removeVertex(ibr, iv)

Remove vertex iv located in branch ibr. The “vertex-mother” in BSMparticles and (SM) particles in the vertex are removed from the branch. The vertex index corresponds to the BSM decay (iv = 0 will remove the first BSM particle,…)

Parameters

• ibr – Index of branch (int)

• iv – Index of vertex in branch ibr (int)

setCoveredBy(resultType)

Tag the element, all its daughter and all its mothers as covered by the type of result specified. It also recursively tags all granddaughters, grandmothers,…

Parameters

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

setEinfo()

Set topology info for each branch.

setTestedBy(resultType)

Tag the element, all its daughter and all its mothers as tested by the type of result specified. It also recursively tags all granddaughters, grandmothers,…

Parameters

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

sortBranches()

Sort branches. The smallest branch is the first one. See the Branch object for definition of branch size and comparison

switchBranches()

Switch branches, if the element contains a pair of them.

Returns

element with switched branches (Element object)

toStr()

Returns a string with the element represented in bracket notation, including the final states, e.g. [[[jet]],[[jet]] (MET,MET)

theory.exceptions module

exception theory.exceptions.SModelSTheoryError(value=None)

Bases: Exception

Class to define SModelS specific errors

theory.lheReader module

class theory.lheReader.LHEParticle

Bases: object

An instance of this class represents a particle.

class theory.lheReader.LheReader(filename, nmax=None)

Bases: object

An instance of this class represents a reader for LHE files.

Constructor.

Parameters

• filename – LHE file name

• nmax – When using the iterator, then nmax is the maximum number of events to be reader, nmax=None means read till the end of the file. If filename is not a string, assume it is already a file object and do not open it.

close()

close file handle

event()

Get next event.

Returns

SmsEvent; None if no event is left to be read.

next()

Get next element in iteration.

Needed for the iterator.

class theory.lheReader.SmsEvent(eventnr=None)

Bases: object

Event class featuring a list of particles and some convenience functions.

add(particle)

Add particle to the event.

getMom()

Return the pdgs of the mothers, None if a problem occurs.

metaInfo(key)

Return the meta information of ‘key’, None if info does not exist.

theory.lheReader.getDictionariesFrom(lheFile, nevts=None)

Reads all events in the LHE file and create mass and BR dictionaries for each branch in an event.

Parameters

• lheFile – LHE file

• nevts – (maximum) number of events used in the decomposition. If None, all events from file are processed.

Returns

BR and mass dictionaries for the particles appearing in the event

theory.lheReader.getDictionariesFromEvent(event)

Create mass and BR dictionaries for each branch in an event.

Parameters

event – LHE event

Returns

BR and mass dictionaries for the branches in the event

theory.model module

class theory.model.Model(BSMparticles, SMparticles, label=None)

Bases: object

An instance of this class holds all the relevant information from the input model. This class contains the input file, the particles of the model and their production cross-sections.

Initializes the model :parameter BSMparticles: list with BSM particle objects :parameter SMparticles: list with SM particle objects :parameter label: Optional string to label the model

filterCrossSections()

Remove cross-sections for even particles or particles which do not belong to the model. Valid cross-sections are stored in self.xsections

Returns

Number of cross-sections after filter.

getEvenOddList()

Get the list of even and odd particles, according to the Z2 parity value defined for each particle.

Returns

list with PDGs of even particles, list with PDGs of odd particles

getModelDataFrom(inputFile)

Reads the input file (LHE or SLHA) and extract the relevant information (masses, widths, BRs and cross-sections). If a http address is given, it will attempt to download the file.

Parameters

inputFile – input file (SLHA or LHE)

Returns

dictionary with masses, dictionary with decays and XSectionList object

getParticlesWith(**kwargs)

Return the particle objects with the listed attributes. MultiParticle objects are added if any of its particles matches the listed attributes. In order to avoid double counting, MultiParticle objects are only included if they do not contain any of the particles already in the list. For instance, if MP.particles = [e-,e+] and [e-] already appears in the list, MP will not be added.

Returns

List of particle objects

getValuesFor(attributeStr)

Returns a list with all the values for attribute appearing in the model.

Parameters

attributeStr – String for the desired attribute

Returns

list of values

setDecays(decaysDict, promptWidth, stableWidth, erasePrompt)

setMasses(massDict, roundMasses, minMass)

Define particle masses using massDict.

Parameters

• roundMasses – If set, it will round the masses to this number of digits (int)

• massDict – dictionary with PDGs as keys and masses as values.

• minMass – Minimal mass for BSM particles in the model. Any particle with mass below minMass will have its mass set to minMass.

updateParticles(inputFile, promptWidth=None, stableWidth=None, roundMasses=1, erasePrompt=['spin', 'eCharge', 'colordim'], minMass=1.00E+00[GeV])

Update mass, total width and branches of allParticles particles from input SLHA or LHE file.

Parameters

• inputFile – input file (SLHA or LHE)

• promptWidth – Maximum width for considering particles as decaying prompt. If None, it will be set 1e-11 GeV.

• stableWidth – Minimum width for considering particles as stable. If None, it will be set 1e-25 GeV.

• roundMasses – If set, it will round the masses to this number of digits (int)

• erasePrompt – If set, all particles with prompt decays (totalwidth > promptWidth) will have the corresponding properties (quantum numbers). So all particles with the same mass and Z2parity will be considered as equal when combining elements.

• minMass – Minimal mass for BSM particles in the model. Any particle with mass below minMass will have its mass set to minMass.

theory.particle module

class theory.particle.MultiParticle(label=None, particles=[], attributesDict={}, **kwargs)

Bases: Particle

An instance of this class represents a list of particle object to allow for inclusive expressions such as jets. The properties are: label, pdg, mass, electric charge, color charge, width

Creates a multiparticle. If a multiparticle with the exact same particles already been created return this multiparticle instead. Assigns an ID to the isntance using the class Particle._instance list. Reset the comparison dictionary.

Parameters

• label – Label for the MultiParticle (string)

• particles – List of Particle or MultiParticle objects (list)

• attributesDict – A dictionary with particle attributes (useful for pickling/unpickling). Attributes can also be directly assigned using keyword arguments.

cmpProperties(other, properties=['Z2parity', 'spin', 'colordim', 'eCharge', 'mass', 'totalwidth'])

Compares the properties in self with the ones in other. If other is a Particle object, checks if any of the particles in self matches other. If other is a MultiParticle object, checks if any particle in self matches any particle in other. If self and other are equal returns 0, else returns the result of comparing the first particle of self with other.

Parameters

• other – a Particle or MultiParticle object

• properties – list with properties to be compared. Default is spin, colordim and eCharge

Returns

0 if properties are equal, -1 if self < other and 1 if self > other.

contains(particle)

Check if MultiParticle contains the Particle object or MultiParticle object.

Parameters

particle – Particle or MultiParticle object

Returns

True/False

getLabels()

labels appearing in MultiParticle :return: list of labels of particles in the MultiParticle

getPdgs()

pdgs appearing in MultiParticle :return: list of pgds of particles in the MultiParticle

isMET()

Checks if all the particles in self can be considered as MET.

Returns

True/False

isNeutral()

Return True if ALL particles in particle list are neutral.

Returns

True/False

class theory.particle.Particle(attributesDict={}, **kwargs)

Bases: object

An instance of this class represents a single particle. The properties are: label, pdg, mass, electric charge, color charge, width

Creates a particle. If a particle with the exact same attributes have already been created return this particle instead. Assigns an ID to the instance using the class Particle._instance list. Reset the comparison dictionary.

Parameters

attributesDict – A dictionary with particle attributes (useful for pickling/unpickling). Attributes can also be directly assigned using keyword arguments.

Possible properties for arguments. Z2parity: int, +1 or -1 label: str, e.g. ‘e-‘ pdg: number in pdg mass: mass of the particle echarge: electric charge as multiples of the unit charge colordim: color dimension of the particle spin: spin of the particle totalwidth: total width

chargeConjugate(label=None)

Returns the charge conjugate particle (flips the sign of eCharge). If it has a pdg property also flips its sign. If label is None, the charge conjugate name is defined as the original name plus “~” or if the original name ends in “+” (“-“), it is replaced by “-” (“+”).

Parameters

label – If defined, defines the label of the charge conjugated particle.

Returns

the charge conjugate particle (Particle object)

cmpProperties(other, properties=['Z2parity', 'spin', 'colordim', 'eCharge', 'mass', 'totalwidth'])

Compare properties (default is spin, colordim and eCharge). Return 0 if properties are equal, -1 if self < other and 1 if self > other. Only compares the attributes which have been defined in both objects. The comparison is made in hierarchical order, following the order defined by the properties list.

Parameters

• other – a Particle or MultiParticle object

• properties – list with properties to be compared. Default is spin, colordim and eCharge

Returns

0 if properties are equal, -1 if self < other and 1 if self > other.

contains(particle)

If particle is a Particle object check if self and particle are the same object.

Parameters

particle – Particle or MultiParticle object

Returns

True/False

copy()

Make a copy of self with a distinct ID.

Returns

A Particle object identical to self, except for its ID and comparison dict

describe()

eqProperties(other, properties=['Z2parity', 'spin', 'colordim', 'eCharge', 'mass', 'totalwidth'])

Check if particle has the same properties (default is spin, colordim and eCharge) as other. Only compares the attributes which have been defined in both objects.

Parameters

• other – a Particle or MultiParticle object

• properties – list with properties to be compared. Default is spin, colordim and eCharge

Returns

True if all properties are the same, False otherwise.

classmethod getID()

classmethod getinstances()

isMET()

Checks if the particle can be considered as MET. If the _isInvisible attribute has not been defined, it will return True/False is isNeutral() = True/False. Else it will return the _isInvisible attribute.

Returns

True/False

isNeutral()

Return True if the particle is electrically charged and color neutral. If these properties have not been defined, return True.

Returns

True/False

isPrompt()

Checks if the particle decays promptly (e.g. totalwidth = inf).

Returns

True/False

isStable()

Checks if the particle is stable (e.g. totalwidth = 0).

Returns

True/False

class theory.particle.ParticleList(particles)

Bases: object

Simple class to store a list of particles.

Creates a particle list. If a list with the exact same particles have already been created return this list instead. Assigns an ID to the instance using the class ParticleList._instance list. Reset the comparison dictionary.

Parameters

particles – List of Particle or MultiParticle objects (list)

classmethod getID()

classmethod getinstances()

theory.theoryPrediction module

theoryPrediction._getElementsFrom(smsTopList, dataset)

Get elements that belong to any of the TxNames in dataset (appear in any of constraints in the result). Loop over all elements in smsTopList and returns a copy of the elements belonging to any of the constraints (i.e. have efficiency != 0). The copied elements have their weights multiplied by their respective efficiencies.

Parameters

• dataset – Data Set to be considered (DataSet object)

• smsTopList – list of topologies containing elements (TopologyList object)

Returns

list of elements (Element objects)

class theory.theoryPrediction.TheoryPrediction(deltas_rel=None)

Bases: object

An instance of this class represents the results of the theory prediction for an analysis.

a theory prediction. deltas_rel is meant to be a constant :param deltas_rel: relative uncertainty in signal (float).

Default value is 20%.

CLs(*args, **kwargs)

analysisId()

Return experimental analysis ID

computeStatistics(*args, **kwargs)

dataId()

Return ID of dataset

dataType(short=False)

Return the type of dataset :param: short, if True, return abbreviation (ul,em,comb)

getRValue(expected=False)

Get the r value = theory prediction / experimental upper limit

getUpperLimit(expected=False)

Get the upper limit on sigma*eff. For UL-type results, use the UL map. For EM-Type returns the corresponding dataset (signal region) upper limit. For combined results, returns the upper limit on the total sigma*eff (for all signal regions/datasets).

Parameters

expected – return expected Upper Limit, instead of observed.

Returns

upper limit (Unum object)

getUpperLimitOnMu(expected=False)

Get upper limit on signal strength multiplier, using the theory prediction value and the corresponding upper limit (i.e. mu_UL = upper limit/theory xsec)

Parameters

expected – if True, compute expected upper limit, else observed

Returns

upper limit on signal strength multiplier mu

getmaxCondition()

Returns the maximum xsection from the list conditions

Returns

maximum condition xsection (float)

likelihood(*args, **kwargs)

lmax(*args, **kwargs)

lsm(*args, **kwargs)

muhat(*args, **kwargs)

nllToLikelihood(nll: Union[None, float], return_nll: bool)

if not return_nll, then compute likelihood from nll

setStatsComputer()

Creates and instance of StatsComputer depending on the type of TheoryPrediction/dataset. In case it is not possible to define a statistical computer (upper limit result or no expected upper limits), set the computer to ‘N/A’.

sigma_mu(*args, **kwargs)

property statsComputer

totalXsection()

whenDefined()

Returns the function whenever the statistical calculation is possible (i.e. when it is possible to define self.StatsComputer)

class theory.theoryPrediction.TheoryPredictionsCombiner(theoryPredictions: list, slhafile=None, deltas_rel=None)

Bases: TheoryPrediction

Facility used to combine theory predictions from different analyes. If a list with a single TheoryPrediction is given, return the TheoryPrediction object.

Constructor. :param theoryPredictions: the List of theory predictions :param slhafile: optionally, the slhafile can be given, for debugging :param deltas_rel: relative uncertainty in signal (float).

Default value is 20%.

analysisId()

Return a string with the IDs of all the experimental results used in the combination.

dataId()

Return a string with the IDs of all the datasets used in the combination.

dataType(short=False)

Return its type (combined) :param: short, if True, return abbreviation (anacomb)

describe()

returns a string containing a list of all analysisId and dataIds

getLlhds(muvals, expected=False, normalize=True)

Facility to access the likelihoods for the individual analyses and the combined likelihood. Returns a dictionary with the analysis IDs as keys and the likelihood values as values. Mostly used for plotting the likelihoods.

Parameters

• muvals – List with values for the signal strenth for which the likelihoods must be evaluated.

• expected – If True returns the expected likelihood values.

• normalize – If True normalizes the likelihood by its integral over muvals.

getmaxCondition()

Returns the maximum xsection from the list conditions

Returns

maximum condition xsection (float)

classmethod selectResultsFrom(theoryPredictions, anaIDs)

Select the results from theoryPrediction list which match one of the IDs in anaIDs. If there are multiple predictions for the same ID for which a likelihood is available, it gives priority to the ones with largest expected r-values.

Parameters

• theoryPredictions – list of TheoryPrediction objects

• anaIDs – list with the analyses IDs (in string format) to be combined

Returns

a TheoryPredictionsCombiner object for the selected predictions. If no theory prediction was selected, return None.

setStatsComputer()

Creates and instance of StatsComputer depending on the type of TheoryPrediction/dataset. In case it is not possible to define a statistical computer (upper limit result or no expected upper limits), set the computer to ‘N/A’.

totalXsection()

theory.theoryPrediction.theoryPredictionsFor(expResult, smsTopList, maxMassDist=0.2, useBestDataset=True, combinedResults=True, deltas_rel=None)

Compute theory predictions for the given experimental result, using the list of elements in smsTopList. For each Txname appearing in expResult, it collects the elements and efficiencies, combine the masses (if needed) and compute the conditions (if exist).

Parameters

• expResult – expResult to be considered (ExpResult object), if list of ExpResults is given, produce theory predictions for all

• smsTopList – list of topologies containing elements (TopologyList object)

• maxMassDist – maximum mass distance for clustering elements (float)

• useBestDataset – If True, uses only the best dataset (signal region). If False, returns predictions for all datasets (if combinedResults is False), or only the combinedResults (if combinedResults is True).

• combinedResults – add theory predictions that result from combining datasets.

• deltas_rel – relative uncertainty in signal (float). Default value is 20%.

Returns

a TheoryPredictionList object containing a list of TheoryPrediction objects

theory.topology module

class theory.topology.Topology(elements=None)

Bases: object

An instance of this class represents a topology.

Constructor. If elements is defined, create the topology from it. If elements it is a list, all elements must share a common global topology.

Parameters

elements – Element object or list of Element objects

addElement(newelement)

Add an Element object to the elementList.

For all the pre-existing elements, which match the new element, add weight. If no pre-existing elements match the new one, add it to the list. OBS: newelement MUST ALREADY BE SORTED (see element.sort())

Parameters

newelement – element to be added (Element object)

Returns

True, if the element was added. False, otherwise

checkConsistency()

Check if the all the elements in elementList are consistent with the topology (same number of vertices and final states)

Returns

True if all the elements are consistent. Print error message and exits otherwise.

describe()

Create a detailed description of the topology.

Returns

list of strings with a description of the topology

getElements()

Get list of elements of the topology.

Returns

elementList (list of Element objects)

getTotalWeight()

Return the sum of all elements weights.

Returns

sum of weights of all elements (XSection object)

class theory.topology.TopologyList(topologies=[])

Bases: object

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

Add topologies sequentially, if provided.

add(newTopology)

Check if elements in newTopology matches an entry in self.topos.

If it does, add weight. If the same topology exists, but not the same element, add element. If neither element nor topology exist, add the new topology and all its elements.

Parameters

newTopology – Topology object

addElement(newelement)

Add an Element object to the corresponding topology in the list. If the element topology does not match any of the topologies in the list, create a new topology and insert it in the list. If the element topology already exists, add it to the respective topology. :parameter newelement: element to be added (Element object) :returns: True, if the element was added. False, otherwise

addList(topoList)

Adds topologies in topoList using the add method.

compressElements(doCompress, doInvisible, minmassgap)

Compress all elements in the list and include the compressed elements 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)

describe()

Returns string with basic information about the topology list.

getElements()

Return a list with all the elements in all the topologies.

getTotalWeight()

Return the sum of all topologies total weights.

hasTopology(topo)

Checks if topo appears in any of the topologies in the list.

Parameters

topo – Topology object

Returns

True if topo appears in the list, False otherwise.

index(topo)

Uses bisect to find the index where of topo in the list. If topo does not appear in the list, returns None.

Parameters

topo – Topology object

Returns

position of topo in the list. If topo does not appear in the list, return None.

insert(index, topo)

Module contents