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: theory.branch.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: smodels.theory.element.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.

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

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.

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)

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.

updateParticles(inputFile, promptWidth=None, stableWidth=None, roundMasses=1, erasePrompt=['spin', 'eCharge', 'colordim'])

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-8 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)
• erasePromptQNs – 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.

theory.particle module

class theory.particle.MultiParticle

Bases: theory.particle.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

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

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

Bases: object

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

analysisId()

Return experimental analysis ID

computeStatistics(marginalize=False, deltas_rel=0.2)

Compute the likelihoods, chi2 and expected upper limit for this theory prediction. The resulting values are stored as the likelihood, lmax, lsm and chi2 attributes (chi2 being phased out). :param marginalize: if true, marginalize nuisances. Else, profile them. :param deltas_rel: relative uncertainty in signal (float). Default value is 20%.

dataId()

Return ID of dataset

dataType(short=False)

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

describe()

getLikelihood(mu=1.0, marginalize=False, deltas_rel=0.2, expected=False)

get the likelihood for a signal strength modifier mu :param expected: compute expected, not observed likelihood

getRValue(expected=False)

Get the r value = theory prediction / experimental upper limit

getUpperLimit(expected=False, deltas_rel=0.2)

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.
• deltas_rel – relative uncertainty in signal (float). Default value is 20%.

Returns:

upper limit (Unum object)

getmaxCondition()

Returns the maximum xsection from the list conditions

Returns:maximum condition xsection (float)

likelihoodFromLimits(mu=1.0, marginalize=False, deltas_rel=0.2, expected=False, chi2also=False, corr=0.6)

compute the likelihood from expected and observed upper limits. :param expected: compute expected, not observed likelihood :param mu: signal strength multiplier, applied to theory prediction. If None,

then find muhat

Parameters:

• chi2also – if true, return also chi2
• corr – correction factor: ULexp_mod = ULexp / (1. - corr*((ULobs-ULexp)/(ULobs+ULexp))) a factor of corr = 0.6 is proposed.

Returns:

likelihood; none if no expected upper limit is defined.

class theory.theoryPrediction.TheoryPredictionList(theoryPredictions=None, maxCond=None)

Bases: object

An instance of this class represents a collection of theory prediction objects.

Initializes the list.

Parameters:

• theoryPredictions – list of TheoryPrediction objects
• maxCond – maximum relative violation of conditions for valid

results. If defined, it will keep only the theory predictions with condition violation < maxCond.

append(theoryPred)

sortTheoryPredictions()

Reverse sort theoryPredictions by R value. Used for printer.

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

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)
• 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.
• marginalize – If true, marginalize nuisances. If false, profile them.
• 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